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Introduction 



MM y elcome to Jakarta Struts For Dummies, your plain-English guide to the 
▼ ▼ Java programming framework that everyone is talking about. In this 
book, we explain how to use Struts to support your Java-based Web develop- 
ment. Jakarta Struts For Dummies gives you all the information you need to 
start using Jakarta Struts — so that you can create better code right away. 



About This Book 

As if you didn't know, Jakarta Struts For Dummies covers Jakarta Struts, the 
popular, open-source framework for creating Web applications in Java. 

We comprehensively explain the features in Jakarta Struts, including the 
following: 

V How Jakarta Struts structures Web application code into three groups — 
Model, View, and Controller — and how this helps make your code 
easier to write and maintain 

How Struts works with a Web container, JavaServer Pages, and Java 
servlets 

Integrating Struts into a Web development environment 

V Controlling your application's business logic 

Representing your data, whether a few items or a huge and complex 
database 

Designing the view — the JavaServer Pages that the application presents 
to the user 

Internationalizing a Web application and using the internationalization 
feature to create easy-to-update text content, even if you care about only 
one language 

u* Validating data 

How the configuration files hold all the parts together 

Using plug-ins to extend Jakarta's functionality 
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I v 0 Using tag libraries 

Using Java Server faces 



tiles help you to dynamically create pages 
f Securing your application 
Logging for troubleshooting 



Hou? to Use This Book 

You don't have to read this book from cover to cover. Jakarta Struts For 
Dummies provides just the information you need, when you need it. If you 
already have your Web development environment set up, you don't need to 
read all of Chapter 2, for example. However, we do suggest that you skim that 
chapter to understand the environment we use in the book, so that you can 
adjust your steps accordingly. 

For additional information, don't ignore Part V, where we explain ten helpful 
extensions to Jakarta Struts and ten ways to get more information. In Part VI, 
we list the syntax of the Struts-EL and JSTL tag libraries and provide a glossary. 

So that you don't have to tire out your fingers, you can find code for this 
book at www . dummi es.com/go/jakarta. 

Keep Jakarta Struts For Dummies handy while you work. You'll find that it's a 
useful resource. 



Foolish Assumptions 

We know that you want an easy-to-understand, logical explanation of how 
to incorporate Jakarta Struts into your programming environment. Our first 
assumption is that because you're a Web developer, you're not a dummy! We 
also assume that you know Java and understand how to create JavaServer 
Pages. You understand also the overall concepts involved in creating a Web 
application. 

You can use any IDE (Integrated Development Environment) that you want, or 
you can write your code in a simple text editor. However, we chose to use an 
IDE so that we can give you the specific steps that you need to take to create 
a complete Web application. That IDE is Eclipse, an open-source, full-featured 
IDE. If you choose a different IDE, we assume that you understand your IDE 
well enough to figure out the parallel commands that we provide for Eclipse. 
Alternatively, you can use Eclipse while you're getting up to speed with Struts 
and then go back to your previous IDE. Who knows, maybe you'll find that 
you like Eclipse as much as we do! 
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Finally, we assume that you know your operating system. We use Windows 
for this book, but you should be able to use this book with Linux or Mac OS, 
le. After all, cross-platform usability is one of the reasons you use 
it? 



Just in case, here a few of the most common PC-to-Mac conversions for key- 
board strokes and mouse movements: 

PC Mac 



Ctrl Command (§§) 

Right-click Ctrl-click 

Enter Return 

Alt Option 



Contentions Used in This Book 

A typographical convention is not a convention of typists. Instead, a typo- 
graphical convention helps you to know why some text is bold and other is 
italic so that you can figure out what we're talking about. New terms are in 
italic. Text that you need to type is bold. (If the text that you need to type is 
in an entire sentence that's bold, the text you type is not bold, to create a con- 
trast.) Messages and other text that come from Jakarta Struts are in a special 
typeface, like this. Code in a paragraph uses the same special typeface. 

When we say something like "Choose FileOSave As," it means to click the File 
menu and then choose Save As from the menu that appears. When we want 
you to use a toolbar button, we tell you to click the button. 



Hou) This Book Is Organized 

We start by introducing you to Jakarta Struts and its concepts. We help you 
collect the pieces you need for a complete Web development environment 
and then introduce you to a simple Web application. Then we drill deep into 
the processes you need to understand to use Struts as you create a Web 
application. 

More specifically, this book is divided into five parts. Each part contains two 
or more chapters, and each part functions as a whole to explain how Jakarta 
Struts works. 
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Part 1: Getting to Knou) Jakarta Stmts 

tains important introductory information about Jakarta Struts, 
what it is and how to start using it. Chapter 3 takes you through the 
steps of creating a simple logon application from beginning to end so that you 
can get the big picture and understand the details that follow in the rest of the 
book. You can download all the code from www. dummi es. com /go/ Jakarta, 
giving you more time to understand, place, and deploy the application. 



Part 11: Starting from the Care 

Part II settles into the three groups that make up the Struts framework: the 
Controller (Chapter 4), the Model (Chapter 5), and the View (Chapter 6). In 
Chapter 7, we explain how to use the configuration files. This part contains all 
the concepts that you need to know to use Struts for creating Web applications. 

Part 111: Expanding \lour Development 
Options 

Part III offers some additional tools and techniques that any programmer can 
use. Chapter 8 covers exception handling. Chapter 9 explains how to use plug- 
ins. Chapter 10 reviews the tag libraries as well as how to use Java Server faces 
and create custom tabs. Chapter 1 1 discusses page composition techniques 
including server side i ncl udes and tiles. Chapter 12 is all about securing 
your application. 



Part IV: Putting It Alt Together 

Part IV starts with a chapter on using logging to troubleshoot any problems 
that might come up. (But that never happens to you, does it?) Then we intro- 
duce a music collection application as a thorough example of the process of 
developing an application using Struts. 



Part V: The Part of Tens 

No For Dummies book is complete without its part of tens — it's a long- 
standing tradition. Chapter 15 reviews ten helpful extensions to Struts, 
and Chapter 16 offers you ten ways to find more information about Struts. 
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Part (A: Appendixes 



put the book, we use tags from the Struts-EL and JSTL tag libraries, 
easy reference, Appendix A includes the syntax for all the tags in 
these libraries. Appendix B is a glossary of the terms we use in this book, just 
to make sure that you understand what we're saying! 



Icons Used in This Book 






If you see little pictures in the margins, you've found an icon. Icons highlight 
special information in the text and let you know if you need to look more 
carefully or if you can just skip to more important parts. 

This icon alerts you to information that you need to keep in mind to avoid 
wasting time or falling on your face. 



Jakarta Struts has some advanced features you may want to know about ■ 
or not. This icon lets you know when we get into some heavy details 



Tips help you complete a task more easily, quickly, or effectively. Don't skip 
these. 



This icon is telling you to play close attention. Otherwise, you never know 
what may happen. 



Where to Go from Here 

Enough of all this talk. Let's move into the real content of this book and start 
using Jakarta Struts. 

If you want, review the table of contents to see which parts interest you. Or 
just turn the page and start reading. Happy programming. Enjoy! 
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In this part . . . 

7 his is where you find out what Jakarta Struts is and 
what it can do for your Web applications. We explain 
how Jakarta Struts fits into the architecture of a Web 
application, including the Web container, Java Server 
Pages, and Java Servlets. We show you how Jakarta Struts 
organizes and structures your application for easy coding 
and maintenance. 

In case you don't already have all the pieces necessary to 
create Web applications, in Chapter 2 we run through the 
process of obtaining and installing an entire Web develop- 
ment environment. In Chapter 3 we describe a simple Web 
application created using Jakarta Struts. 




Chapter 1 



In This Chapter 

Getting an overview of Jakarta Struts 
Creating the structure of a Web application 
Understanding the Model- View-Controller paradigm 




^kuppose that you're a programmer and your job is creating Web applica- 

tions. You know the basics of Web applications. You use the Java pro- 
gramming language because of its power and flexibility. To make the Web 
pages interactive, you create Java Servlets and JavaServer Pages (JSP). 
You're getting pretty good at what you do, so your Web applications are 
becoming more complex. 

You've heard the buzz about Jakarta Struts and how it can help structure 
leaner, tighter Web applications. You want to know how you can make use 
of this powerful programming framework to make your application program- 
ming more systematic and consistent, while taking less time. In this chapter, 
we explain what Jakarta Struts is all about and how it fits into the scheme of 
a Web application. 



Jakarta Struts is incredibly useful in helping you create excellent Web appli- 
cations. When you use Jakarta Struts, your applications should work more 
effectively and have fewer bugs. Just as important (because your time is 
important), Struts should save you hours and hours of programming and 
debugging. 

As we explain more fully later in this chapter, Struts is a framework that struc- 
tures all the components of a Java-based Web application into a unified whole. 
These components of a Web application are 

I is* Java Servlets: Programs written in Java that reside on a Web server and 
respond to user requests 
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**" JavaServer Pages: A technology for generating Web pages with both 
static and dynamic content 



Beans: Components that follow specific rules, such as naming 
entions 



Business logic: The code that implements the functionality or rules of 
your specific application 

We provide an overview of the first three items in this chapter. (The business 
logic varies with each application.) 

Jakarta Struts uses a specific paradigm, or design pattern, to structure your 
application. You simply fill in the pieces of the structure. The design pattern 
is called Model-View-Controller (MVC). The MVC design pattern helps you 
organize the various pieces of the application puzzle for maximum efficiency 
and flexibility. We explain MVC later in this chapter and expand on the Model, 
View, and Controller concepts in Chapters 4, 5, and 6. 



Structuring a Web Application 



We define a Web application as a program that resides on a Web server and 
produces static and dynamically created pages in a markup language (most 
commonly HTML) in response to a user's request. The user makes the request 
in a browser, usually by clicking a link on the Web page. Figure 1-1 shows a 
high-level view of Web architecture. We explain the components of this figure 
subsequently in this chapter. 

To build Web applications, you use Java 2 Enterprise Edition (J2EE), which 
provides support for Servlets, JSP, and Enterprise JavaBeans (EJB), a distrib- 
uted, multi-tier, scalable component technology. 



Figure 1-1: 

High-level 
view of Web 
architecture. 



Browser 



Web Server 



Web Container 




Database 
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e does Jakarta Struts come from? 



Jakarta Struts is all about, 
you need to know something about the open- 
source movement that is its heritage. Open- 
source generally refers to software that the 
distributor provides at no cost to the user and 
that includes both the binary (compiled) code 
and the source code. 

You obtain open-source software under a spe- 
cific license, and the license can vary from one 
software provider to another. For example, the 
GNU (www . gnu . org) license provides that you 
must always include the source code if you 
redistribute the software of the application, 
whether or not you have made modifications 
to the original source code. The Apache 
(www .apache .org) license does not require 
you to provide the source code when you redis- 
tribute one of their applications. So open- 
source software licenses vary — check the 
license to be sure. For more information on 
open-source software, take a look at www. 
opensource .org. 

Jakarta is one of many projects under the aus- 
pices of the Apache Software Foundation (ASF) 
(www . apache .org), formerly known as the 
Apache Group. The Apache Group was formed 
in 1995 by a number of individuals who worked 
together to create one of the most successful 
examples of an open-source project, the 
Apache Web Server (used by 64% of the Web 
sites on the Internet as of October, 2003). In 
1999, the Apache Group became the non-profit 
Apache Software Foundation, to better provide 



supportfor its members and a legal presence to 
protect its resources. 

As the popularity of Apache grew, so did ideas 
for other related open-source applications. 
Currently 16 software projects are supported by 
ASF. Actually, software projects is a bit of a mis- 
nomer because many of these projects have 
numerous subprojects that are really indepen- 
dent projects in themselves. Creativity is unlim- 
ited, so the ideas keep coming! 

Jakarta (Jakarta . apache . org) is one of the 
principal 16 ASF projects. To quote from their 
Web site, "Jakarta is a Project of the Apache 
Software Foundation, charged with the cre- 
ation and maintenance of commercial-quality, 
open-source, server-side solutionsforthe Java 
Platform, based on software licensed to the 
Foundation, for distribution at no charge to the 
public." Struts is one of the 22 subprojects cur- 
rently listed. Yes, this entire book is about one 
subproject. 

Struts was created by Craig R. McClanahan and 
donated to ASF in May, 2000. Craig is an 
employee of Sun Microsystems and is the pri- 
mary developer of both Struts and Tomcat 4. You 
can read about Craig and many other Struts 
contributors at jakarta.apache.org/ 
struts/vol unteers . html. The Struts 1.0 
release had 17 contributors. With release 1.1 
that number has jumped to 50. The project was 
named Struts as a reference to the architectural 
structures in buildings and homes that provide 
the internal support. The present version of 
Struts is 1.1. 



A Web container is a program that manages the components of a Web applica- 
tion, in particular JSP pages and Java Servlets. A Web container provides a 
number of services, such as 
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Security: Restricted access to components, such as password protection 
Concurrency: The capability to process more than one action at a time 



4? 



cycle management: The process of starting up and shutting down a 
component 

Some people use the term JSP/Servlet container, which means the same thing 
as Web container. We favor Web container — it's shorter and easier to type. 

Apache Tomcat is an example of a Web container — an open-source imple- 
mentation of the J2EE Java Servlet and JavaServer Pages (JSP) specifications. 
A specification is a document that describes all the details of a technology. 
The implementation is the actual program that functions according to its 
specification. In fact, Apache Tomcat is the official reference implementation 
for the J2EE Java Servlet and JSP specifications. As a result, Apache Tomcat 
is a popular Web container for Web applications that use JSP and Servlets, 
including applications that use Struts. We use Tomcat in all the examples in 
this book. However, many other commercial and open-source Web containers 
are available. 



Typically, a Web container also functions as a Web server, providing basic 
HTTP (Hypertext Transfer Protocol) support for users who want to access 
information on the site. When requests are for static content, the Web server 
handles the request directly, without involving Servlets or JSP pages. 

However, you may want your Web pages to adapt in response to a user's 
request, in which the response is dynamic. To generate dynamic responses, 
the Servlet and JSP portion of the container gets involved. Tomcat has the 
capability to act as both a Web server and a Web container. However, it also 
can interact with a standard Web server, such as Apache Web Server, letting 
it handle all static requests and getting involved only when requests require 
Servlet and JSP service. 



Usinq JaVa Sertftets 

Java Servlets extend the functionality of a Web server and handle requests 
for something other than a static Web page. They are Java's answer to CGI 
(Common Gateway Interface) scripts of olden times (5 to 6 years ago). As 
their name implies, you write Java Servlets in Java and usually extend the 
HttpServl et class, which is the base class from which you create all 
Servlets. As such, Java Servlets have at their disposal the full functionality 
of the Java language, which give them a lot of power. 

Servlets need to run in a Web container, an application that adheres to the 
Java Servlet Specification. In most cases, the container will support also the 
JavaServer Pages Specification. You can find a list of products supporting the 
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Java Servlet and JSP specifications at Java. sun. com/products / servlet/ 
i ndus try . html . The latest Java Servlet Specification is 2.3, and the latest 
;er Pages Specification is 1.2. 
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Creating JatfaSerVer Pages 



You use JavaServer Pages to present dynamic information to the user in a 
Web page. A JSP page has a structure like any static HTML page, but it also 
includes various JSP tags, or embedded Java scriptlets (short Java code frag- 
ments), or both. These special tags and scriptlets are executed on the server 
side to create the dynamic part of the presentation, so that the page can 
modify its output to reflect the user's request. 



What really happens behind the scenes is that the JSP container translates 
the JSP page into a Java Servlet and then compiles the Servlet source code 
into runnable byte code. This translation process happens only the first time 
a user accesses the JSP page. The resulting Servlet is then responsible for 
generating the Web page to send back to the user. 




Each time the JSP page is changed, the Web container translates the JSP page 
into a Servlet. 



Listing 1-1 shows an example of a JSP page, with the JSP-specific tags in bold. 



Listing 1-1 Sample JSP Page 



1 


<%@ page contentType="text/html ;charset=UTF- 




8"1 anguage=" java" %> 


2 


<%-- JSTL tag libs --%> 


3 


<%@ taglib prefix="fmt" uri="/WEBINF/fmt.tld" %> 


4 


<%- Struts provided Taglibs --%> 


5 


<%@ taglib uri="/WEB-INF/struts-html -el .tld" 




pref ix="html " %> 


6 


<html : html 1 ocal e="true"/> 


7 


<head> 


8 


<fmt : setBundl e basename="Appl i cati onResources" /> 


9 


<ti tl eXf mt : mess age key=" 1 oggedi n . ti tl e" / ></ti tl e> 


10 


</head> 


11 


<body> 


12 


<jsp: useBean id="polBean" 




cl ass="com. othenos . purchasi ng. struts . PO Li stBean"/> 


13 


<H2> 


14 


<fmt : message key=" loggedin.msg"> 


15 


<fmt:param val ue= ' $ 1 pol Bean . userName ) ' /> 


16 


</fmt :message> 


17 


</H2> 


18 


</body> 


19 


</html> 
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jon: Follows the XML (extended Markup Language) format and always 
ns with < j sp : some acti on/>. It provides a way to add more func- 
tionality to JSP, such as finding or instantiating (creating) a JavaBean for 
use later. You see one example of an action tag in line 12 of the code in 
Listing 1-1. 

W Directive: A message to the Web container describing page properties, 
specifying tag libraries, or substituting text or code at translation time. 
The form is <%@ the directive %>. Listing 1-1 has directives on lines 
1, 3, and 5. 

v 0 Declaration: Declares one or more Java variables or methods that you 
can use later in your page. The tag has this form <% ! declaration %>. 

V 0 Expression: Defines a Java expression that is evaluated to a St r i ng. Its 

formis<%= expression 7o>. 

Scriptlet: Inserts Java code into the page to perform some function not 
available with the other tag elements. Its form is <.% Java code 7o>. 

f Comment: A brief explanation of a line or lines of code by the developer. 
Comments have the form <.%- - the comment --%>. Lines 2 and 4 in 
Listing 1-1 are examples of comments. 



Because a JSP file is just a text file, you can create it in just about any kind of 
text editor. Note that some editors understand JSP syntax and can provide 
nice features such as formatting and color coding. A few of the bigger ones are 
Macromedia Dreamweaver (www .macromedi a . com/sof tware/dreamweaver/), 
NetBeans (www. net beans .org), and Eclipse (www . eel i pse . org); the last two 
are complete Java development environments. 

Like Java Servlets, JSP pages must be run in a Web container that provides 
support for JSP technology, as we explained in the preceding section, "Using 
Java Servlets." 



Usinq Jatia&eam 

When you program in Java, you define or use classes that function as a tem- 
plate for objects that you create, k JavaBean is a special form of Java class 
that follows certain rules, including the methods it uses and its naming 
conventions. 



Beans are so useful because they are portable, reusable, and platform indepen- 
dent. Beans are components because they function as small, independent pro- 
grams. JavaBeans component architecture defines how Beans are constructed 
and how they interact with the program in which they are used. 
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|^ ^cc|^ r^^rs to area in which an object 
(such as a Bean or any Java class) can be 
stored. Scopes differ based on the length of 
time stored objects are available for reference, 
aswell as where the objects can be referenced 
from. 



Scope 



In JSP and Struts, 
values: 



scope can be one of four 



Page: Objects in the page scope are avail- 
able only while the page is responding to 
the current request. After control leaves the 
current page, all objects stored in the page 
scope are destroyed. 

Request: Objects in the request scope are 
available as long as the current request is 



being serviced. A request can be serviced 
from more than one page. 

Session: The objects in the session scope 
last as long as the session exists. This could 
be until the user logs out and the session is 
destroyed or until the session times out due 
to inactivity. Each client using the Web 
application has a unique session. 

Application: The longest lasting scope 
is the application scope. As long as the 
application is running, the objects exist. 
Furthermore, objects in the application 



scope are available to al 
application. 



clients using the 




You can call a JavaBean a Bean and everyone will know what you're talking 
about, as long as you're not discussing coffee. 

The JavaBean documentation refers to the rules as design patterns. However, 
this term is more generally used to refer to design patterns such as the 
Model-View-Controller design pattern. Naming conventions is a more appro- 
priate term. 



As an example of the special Bean rules, let's look at properties. A Bean's prop- 
erties that are exposed (public) are available only through the getter and setter 
methods, because the actual property definition is typically private (available 
to only the defining class). The properties follow the naming convention that 
the first letter of the property must be lowercase and any subsequent word 
in the name should start with a capital letter, such asmailingAddress. (We 
explain getters and setters after Listing 1-2.) Listing 1-2 is an example of a 
simple Bean. 

Listing 1-2 Example of a Simple JavaBean 

public class SimpleBean implements Java . i o . Sen' al i zabl e 
( 

private String name; 

// public no-parameter constructor 
publ i c Simpl eBean ( ) 
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getter method for name property 
1 i c Stri ng getName( ) 



return name; 

) 

// setter method for name property 
public void setName( Stri ng aName) 
{ 

name = aName; 



In this example, Stri ng is the type of property and name is the property 

Methods that access or set a property are public (available to anyone using 
the Bean) and also use a certain naming convention. You name these meth- 
ods as follows: 

To get a property's value, the method must begin with get followed by 
the property name with the first letter capitalized, as in publ i c Stri ng 
getName ( ) ; .These methods are called getters. 

V To set a property's value, the method must begin with set followed by 
the property name with the first letter capitalized and the value to set the 
property to, as in publ i c void setName( Stri ng theName) ; .These 
methods are called setters. 
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^jcJABEfl You should also be familiar with special naming conventions for Boolean and 
indexed properties. Many additional requirements exist, but they are less 
important for our situation. See Java. sun. com/docs/books/tutor ial/ 
javabeans/index.html for more information on JavaBean requirements. 



You should follow the JavaBean conventions when creating Beans to ensure 
that the user of the Bean knows how to get information in and out of the com- 
ponent. Classes that use the Beans know that if it's really a Bean, it follows 
the proper conventions; therefore, the class can easily discover the proper- 
ties, methods, and events that make up the Bean. 



In Struts, you commonly use Beans in Web applications and specifically in a 
more restricted manner than in the component architecture we just described. 
You use Beans more often as temporary holding containers for data. For exam- 
ple, suppose that a user requests to see a purchase order. The Web application 
then does the following: 



1. Retrieves a copy of the requested purchase order information from the 
backend database 
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2. Builds a PurchaseOrder Bean 

Populates the Bean with the retrieved data 

the Bean in the JSP page to display the data. 



Because the Web application has transferred the data from the backend data- 
base to the Web page or for access by the business logic, the Bean is called a 
Data Transfer Object (DTO). A DTO is a design pattern. 



Understanding the h\odel-Vieu)~ 
Controller Design Pattern 

Although Struts is not a complete application, it can be customized through 
extension to satisfy your programming needs. By using Struts, you can save 
hundreds, if not thousands, of hours of programming time and be confident 
that the underlying foundation is efficient, robust, and pretty much bug-free. 
When implemented properly, Struts is definitely a boon. 

An application framework is a skeleton of an application that can be cus- 
tomized by the application developer. Struts is an application framework that 
unifies the interaction of the various components of a J2EE Web application — 
namely Servlets, JSP pages, JavaBeans, and business logic — into one consis- 
tent whole. Struts provides this unification by implementing the Model-View- 
Controller (MVC) design pattern. Struts provides an implementation of the 
MVC design pattern for Web applications. To understand why this is so impor- 
tant, you need to see why MVC is such a useful architecture when dealing with 
user interactions. 

The MVC pattern is the grand-daddy of object-orientated design patterns. 
Originally used to build user interfaces (UI) in Smalltalk-80, an early object- 
oriented programming system, it has proved useful everywhere UI's are pre- 
sent. The MVC pattern separates responsibilities into three layers of 
functionality: 

v 0 Model: The data and business logic 

is* View: The presentation 

u 0 Controller: The flow control 

Each of these layers is loosely coupled to provide maximum flexibility with 
minimum effect on the other layers. 
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What is a design pattern} 
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.ession "Don't reinvent the wheel" means that you shouldn't try to 
ommon problem that many bright people have already faced and 
solved in a clever and elegant way For many years, other disciplines (for 
example, architecture) have recognized that repeating patterns of solutions 
exist for common problems. In 1995, an often-quoted book called Design 
Patterns: Elements of Reusable Object-Oriented Software by Gamma, Helm, 
Johnson, and Vlissides (published by Addison-Wesley Publishing Co.) used 
the same technique to formalize problem-solving patterns in the field of 
object-orientated design. 

A design pattern is a blueprint for constructing a time-tested solution to a 
given problem. It's not a concrete implementation; rather, it's a high-level 
design of how to solve a problem. Because design patterns are more general 
than concrete implementations, they are consequently more useful because 
they have broader applications. 



The MVC design pattern 

In the MVC design pattern, the Model provides access to the necessary busi- 
ness data as well as the business logic needed to manipulate that data. The 
Model typically has some means to interact with persistent storage — such 
as a database — to retrieve, add, and update the data. 

The View is responsible for displaying data from the Model to the user. This 
layer also sends user data to the Controller. In the case of a Web application, 
this means that both the request and the response are in the domain of the 
View. 

The Controller handles all requests from the user and selects the view to 
return. When the Controller receives a request, the Controller forwards the 
request to the appropriate handler, which interprets what action to take based 
on the request. The Controller calls on the Model to perform the desired func- 
tion. After the Model has performed the function, the Controller selects the 
View to send back to the user based on the state of the Model's data. 

Figure 1-2 shows the relationships among the three layers. 

To get an idea of why the MVC pattern is so useful, imagine a Web application 
without it. Our fictional application consists of just JSP pages, with no Servlets. 
All the business logic necessary to service a user's request and present the 
user with the desired results is in those JSP pages. Although this scheme is 
simpler than an implementation using MVC, it is also difficult to work with for 
anything but the most trivial application, due to the intermixing of Model, View, 
and Controller elements. 
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Figure 1-2: 

The Model- 
View- 
Controller 
pattern. 



View selection 



User request 



Controller 



Requests state change 



To illustrate the difference between Web applications that don't use MVC 
and those that do, think about the difference between Rocky Road and 
Neapolitan ice cream. Both may be delicious, but if you want to make any 
changes to Rocky Road, think about how much trouble it would be to switch 
the almonds for walnuts. The almonds are too deeply embedded in the ice 
cream to do the switch without affecting everything else. On the other hand, 
because Neapolitan is cleanly separated into layers, switching one flavor for 
another is an easy task. Think of Neapolitan as MVC compliant, and Rocky 
Road as not. 

Using the MVC pattern gives you many advantages: 

Greater flexibility: It's easy to add different View types (HTML, WML, 
XML) and interchange varying data stores of the Model because of the 
clear separation of layers in the pattern. 

Best use of different skill sets: Designers can work on the View, program- 
mers more familiar with data access can work on the Model, and others 
skilled in application development can work on the Controller. Differ- 
entiation of work is easier to accomplish because the layers are distinct. 
Collaboration is through clearly defined interfaces. 

V Ease of maintenance: The structure and flow of the application are clearly 
defined, making them easier to understand and modify. Parts are loosely 
coupled with each other. 



HouJ Stmts enforces the MVC pattern 

The architecture of Struts provides a wonderful mechanism that, when fol- 
lowed, ensures that the MVC pattern remains intact. Although Struts provides 
a concrete implementation of the Controller part of the pattern, as well as pro- 
viding the connections between the Controller and Model layers and between 
the Controller and View layers, it doesn't insist on any particular View para- 
digm or require that you construct the Model in a particular way. 
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The Stmts Controller 

Although Struts does not provide or require any particular Model or View 

^nts of the MVC pattern, it does implement the Controller as well as 
nanisms that bind the three layers and allow them to communicate 
with each other. The primary controller class is a Java Servlet called the 
ActionServlet. This class handles all user requests for Struts-managed 
URLs. Using information in the configuration files, the Acti onServl et class 
then gets the appropriate RequestProcessor class that collects the data 
that is part of the request and puts it into an Acti on Form, a Bean that con- 
tains the data sent from or to the user's form. The final step of the Controller 
is to delegate control to the specific handler of this request type. This han- 
dler is always a subclass of the Acti on class. Figure 1-3 shows how Struts 
uses the MVC pattern. 

The Acti on subclass is the workhorse of the Controller. It looks at the data 
in the user's request (now residing in an Acti on Form) and determines what 
action needs to be taken. It may call on the business logic of the Model to 
perform the action, or it may forward the request to some other View. The 
business logic may include interacting with a database or objects across the 
network or may simply involve extracting some data from an existing 
JavaBean. 

After the necessary action has been performed, the Acti on subclass then 
chooses the correct View to send back to the user. The View is determined by 
the current state of the Model's data (the model state) and the specifications 
you defined in the Struts configuration file. (For an explanation of the configu- 
ration file, see the "The Struts configuration file" section later in this chap- 
ter). Figure 1-4 shows the principal classes of the Struts Controller. 
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JSP 
page 



Action 



JavaBean 



Chapter 1: Starting with the Basics 



DBooks 



ActionServlet 



Figure 1-4: 
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The Struts Vieitf 

As mentioned, Struts does not provide, nor is it dependent on, a specific pre- 
sentation technology. Many Struts applications use JSP (JavaServer Pages) 
along with the Struts tag library (Struts and Struts-EL), JSTL (JSP Standard 
Tag Library), and JSF (Java Server Faces). Some other possibilities are 



Apache Cocoon (cocoon .apache . org/) 

f* Jakarta Velocity templates (Jakarta, apache, org/velocity/ 
i ndex . html) 

is 0 XSLT (extensible Stylesheet Language Transformation) (www .w3.org/ 
TR/xslt) 
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The JSP specification provides for the creation of HTML-like tags that extend 
the functionality of JSP. These custom tags are bundled by their creators into 
custom tag libraries and are accompanied by a descriptor file called a Tag 
Library Descriptor (tld). The Struts and Struts-EL tag libraries are examples 
of this extended functionality. 

Our examples throughout the book use JSP along with Struts-EL, JSTL, and 
other tag libraries. (For more on tag libraries, see Chapter 10.) 

For new projects, the recommendation from the Struts Web site is to use not 
the standard Struts tag libraries, but instead the Struts-EL tag library along 
with JSTL. The Struts-EL tags library is really a reimplementation of the stan- 
dard Struts tag library to make it compatible with JSTL's method of evaluat- 
ing values. However, when a JSTL tag implemented the same functionality, 
the Struts tag was not reimplemented in the Struts-EL library. See Jakarta . 
apache . org/struts/f aqs/struts-el . html for full details on the Struts-EL 
tag library. 
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The Stmts Model 

Nqthing in Struts dictates how to construct the Model. However, the best 

is to encapsulate the business data and operations on that data into 
Is, as we described previously when discussing Data Transfer Objects 
(in the "Using JavaBeans" section). The data and operations may reside in the 
same class or in different classes, depending on your application. 



The operations represent the business logic that your application is defining. 
Operations may be the rules that should operate on a particular business entity. 
For example, if you're writing a purchasing system, part of the business data 
might be an entity called a Purchase Order. You may encapsulate this data into a 
class called PurchaseOrderasa way of representing the Purchase Order entity. 
Furthermore, you may choose to place your business rules directly into this 
class, or you may choose to put the rules into a different class. 

The connection between the Controller and Model rests in the code that you 
write in the Acti on subclasses. The Acti on subclasses contain the analysis 
of the user's request that determines the interaction (if any) with the Model. 
Some examples of that interaction are 

is* Creating a JavaBean (like the PurchaseOrder class example above) that 
in turn accesses a database to populate itself and then makes it available 
to subsequent Views. 

i>* Referencing a business logic object and asking it to perform some opera- 
tion based on incoming data from the user. 

The Acti on subclass initiates any action required to handle a user's request, 
thereby creating the connection with the Model. 

When formulating a response, the Controller may pass some or all of the 
Model data to the View through the use of the Acti on Form Bean. Although 
this Bean is a data container, it should not be considered part of the Model 
but rather just a transport mechanism between the Model and the View. Just 
as often, the View may directly reference the Model's data by referencing one 
or more of the Beans that belong to the Model. 

The standard MVC pattern describes an interaction between the Model and 
the View so that when the Model's data changes, it can immediately push 
those changes out to the View so the user sees them. However, this is more 
difficult to achieve in the Web application architecture. Consequently, the 
View is commonly updated by the user requesting it. 
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The Stmts configuration file 

configuration file performs an important role in structuring your 
plication. Although it is not really part of the Model, View, or 
it does affect the functioning of the three layers. The configuration 
file allows you to define exactly which of your Action subclasses should be 
used under what circumstances and which ActionForm should be given to 
that Acti on subclass. So you specify part of the Controller interaction in the 
configuration file. 

In addition, when the Controller decides which View to return to the user, it 
chooses the particular View according to specifications in the configuration 
file. Thus the configuration file actually defines many of the connections 
between the MVC components. The beauty of the configuration file is that 
you can change the connections without having to modify your code. The 
configuration file does much more than defining connections, which is why 
we devote all of Chapter 7 to the configuration file. 
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In This Chapter 

Installing Java 

Installing the Web container 

Choosing a development environment 

Installing Eclipse 

Getting the Tomcat Launcher 

Installing Jakarta Struts 

Testing your application 



1 

m n this chapter, we explain all the necessary preparations to actually start 
«C using Struts. We also specify what you need to do to create the sample 
Struts application that we introduce in Chapter 3. 

To get ready to use Struts, you need to gather several tools, install them, and 
make sure they're in working order. 

You must download and install five items to follow the examples in the book. 
Each one is free and open source: 

The Java environment: Used for development and running the Web 
container. 

V The Web container application: We use Jakarta Tomcat because it's the 
reference implementation for the JSP and Servlet specification, as we 
explain in Chapter 1. 

f A Java integrated development environment (IDE): We chose Eclipse, 
the popular open-source IDE. Eclipse is a fine tool with plenty of features 
to help the programmer. 

V A plug-in for the IDE: We use Sysdeo Eclipse Tomcat Launcher to assist 
in running applications in Tomcat. 

The Struts framework: What this entire book is about! 
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1^ I J ^) ^^tje^i^jstep in preparing to use Struts is to ensure that you have an up-to 
date v 



date version of Java. This is a primary consideration: All your work in Struts 
depends on having the proper version of Java. 

If you already installed a recent version (1.3 or later) of the Java Standard 
Edition SDK (Software Development Kit), you can skip this step and jump 
ahead to the next section, "Getting the Web Container." Note that we said 
SDK, not JRE (Java Runtime Environment). Tomcat, the Web container, 
requires the compiler in the SDK version to compile the JSP pages. 



botinloadinq and instaliinq JaVa 

Before installing a recent version of Java, you need to uninstall any previous 
versions. You need at least 120MB of disk space to install the SDK. Windows 
2000 or XP users must have administrator privileges to perform the installation. 

The exact steps to download and install Java depend on your operating system. 
To download and install Java in a Windows environment, follow these steps: 

1. Go to java .sun . com/j2se/downl oads . html . 

2. Click the link for the latest SDK version of J2SE (1.4.2 as of this writing). 

The Download page for the version you chose appears, as shown in 
Figure 2-1. 

You can download many things from this page. The only one you need 
for this book is the one labeled Down 1 oad J2SE v 1 . 4 . 2_03. Ignore the 
others and choose the SDK for your operating system. 

3. Click the Download link for your operating system. 

The License Agreement appears. 

4. Read the License Agreement. Scroll down to the bottom and click 
Accept. 

The Java installation file link appears. 

5. Click the Java installation file link. 

The File Download dialog box appears. 

6. Click Save. 

The Save As dialog box appears. 
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Figure 2-1: 

The 
Download 
page for 
J2SE. 
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7. Choose a location for the installation file and then click Save. 

Jot down the location — you'll need it later. 

8. When the download is complete, locate and double-click the installa- 
tion file. 

The InstallShield Wizard opens. 

9. Follow the instructions in the InstallShield Wizard to install Java 
Standard Edition SDK. 

To test your installation, display a command prompt as follow. In Windows, 
choose StarK>(AH) ProgramsOAccessoriesOCommand Prompt. Type the fol- 
lowing command: 

java -version 

Java responds with the version information about the SDK you just installed, 
as shown in Figure 2-2. 




When installing the Java SDK, two JREs are installed by default. One JRE is in 
the home directory of the SDK and is considered private. The other JRE is 
generally installed in the Program Files directory of the system volume. This 
second JRE is considered the public JRE. 
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Setting the JaVa Home 
environment Variable 



If you want to follow our examples by using Tomcat as the Web container, you 
also need to set an environment variable so that Tomcat can find and use the 
Java environment. This variable is JAVA_H0ME, and you set it to the installed 
location of the SDK. 

The procedure for setting this variable depends on your operating system. 
To set this variable in Windows 2000 and XP, follow these steps: 

1. Choose StartOControl Panel. 

If you're using the Classic theme, choose StartOSettingsOControl Panel. 

2. Double-click the System icon. 

3. Click the Advanced tab. 

4. Click the Environment Variables button. 

5. In the System Variables section, click the New button. 
The Edit System Variable dialog box appears. 

6. In the Variable Name text box, type JAVA_HOME. 

7. In the Variable Value text box, type the full path to the installation 
folder, as shown in Figure 2-3. 

8. Click OK three times to close all the dialog boxes and the Control 
Panel. 



Figure 2-3: 

Setting the 
JAVA_ 
HOME 
environmen- 
tal variable. 



Edit System V.nialile 



Variable name: 



Variable value: c:\j2sdkl. 4. 2_03| 
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amples of Web applications in this book, we assume that you're 
using the Tomcat Web container, version 4.1.x Of course, you can choose 
whatever container you please, as long as it supports the Servlet 2.3 and 
JSP 1.2 specifications. 



Downloading Tomcat to Windows 

To download Tomcat to Windows NT, 2000, or XP, follow these steps: 

1. Go to Jakarta . apache . org /tomcat/ i ndex. html . 

2. In the Downloads menu on the left, click the Binaries link. 
The Binary Downloads page appears. 

3. Scroll down (quite a bit) until you see the Tomcat 4.1.29 KEYS link. 

Tomcat 4.1.29 is the latest version as of this writing. 

Each Tomcat link includes KEYS and PGP links. Each binary version of 
Tomcat (in fact, all Jakarta project binaries) is digitally signed by the 
developers. To verify that the binary version you download is intact, you 
download the public KEY. Then you use the public domain PGP program 
to check the key against the PGP signature. To see how to do this, take a 
look at www .apache week, com /issues/01 - 06- 01. You can verify Tomcat 
if you want, or you can simply download Tomcat without verification. 

4. Click one of the links below the Tomcat 4.1.29 KEYS link. 

We suggest choosing the Tomcat 4.L29.exe link instead of the 4. 1.29. zip 
link because the . exe file automatically installs shortcuts for starting 
and stopping Tomcat. The File Download dialog box appears. 

5. Click the Save button. 

The Save As dialog box opens. 

6. Choose a location for the file and then click Save. 

Remember where you put the downloaded file. 



Installing Tomcat under Windows 

After you download the Tomcat installation file, you need to install Tomcat. 
The instructions vary according to your operating system. Here we provide 
instructions for Windows. After these steps, we refer you to online resources 
that provide installation instructions for Linux and Mac OS. 
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To install Tomcat under Windows, follow these steps: 
ble-click the installation file. 



alog box appears, explaining that Tomcat has found your Java 
installation. 

2. Click OK. 

The License Agreement opens. 

3. Read the License Agreement and then click the I Agree button. 

The Installation Options dialog box appears, shown in Figure 2-4. 



Figure 2-4: 

The 
Installation 
Options 
dialog box. 
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4. Keep the default installation values and then click Next. 

The Installation Directory dialog box appears. 

5. Change the path so that Tomcat is in the root of the drive and rename 
the folder by replacing the blank space between Tomcat and 4.1 with 
a hyphen or an underscore, as shown in Figure 2-5. 

Sometimes we experience problems with DOS commands when the path 
name contains blank spaces; eliminating blank spaces reduces the 
chance for problems later. 



Figure 2-5: 

Setting the 
installation 
directory. 



=| Apache Tomcat 4.1.29 Setup: Installation Diiectory 


U Please select a location to install Tomcat 41 (o 


use the default): 


Select the directory to install Apache Tomcat 4 1 .29 in: 




|D:\Tomcatj4.1 


Browse... | 


Space required: 32.4MB 




Space available: 214.-1GB 




Cancel | Nullsoft install System vl 98 


< Sack | Install | 





Chapter 2: Laying the Groundwork 



ipBooks 

7. If yo 



6. Click the Install button. 

The Installer puts the files into the location you specified. Then the 
ing Installer Options dialog box appears. 



you don't have a Web server program installed and running, change 
the port from 8080 to 80. 

If you already have a Web server such as Apache or IIS, just leave the 
port number at 8080. 

The standard Web server port is 80 and consequently does not need to 
be specified in the browser URL. If you leave the port at 8080, remember 
that all requests to Tomcat must specify port 8080. For example, you 
need to enter http://localhost:8080/index.jsp instead of http : // 
localhost/index.jspto display the index.jsp page in your browser. 

8. In the Password text box, type a password and then click Next. 

The Setup program completes the Tomcat installation. 

9. Click Close. 

Congratulations! You successfully installed Tomcat. 



Installing Tomcat under Linux or Mac OSX 

If you need to install Tomcat on Linux, refer to the instructions at the following: 



www . cymul acrum . net /tomcat 


/ 


tomcat_i nstal 1 . html #2 













Be sure to download the full Tomcat, not just the LE (Lite) version. 



Installing Tomcat on OS X is a snap. Refer to the documentation on the Apple 
Developers site at developer, apple, com/ i internet/ java/tomcatl. html. 



Port numbers 



Ports are numbered network connectors that a 
computer uses to communicate using the Inter- 
net's Transmission Control Protocol (TCP). Gen- 
erally, port numbers 0 through 1023 are reserved 
for well-known functions such as ftp or telnet. 

For Web applications, remember that port 80 
is reserved for HTTP protocol (Web server) 
communications. 



Ports from 1024 through 49151 are registered 
ports. This means those port numbers must be 
registered with Internet Corporation for Assigned 
Names and Numbers (ICANN), much like 
domain names must be registered. Port 8080 is 
registered for use for the Tomcat Web server 
application. 

Port numbers from 49152 through 65535 can be 
used by anybody for any reason. 
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Starting and testing Tomcat 



i install Tomcat, you should start it and test it. To start Tomcat, 
tartO(All) ProgramsOApache Tomcat 4.10Start Tomcat. The Start 
Tomcat screen appears, as shown in Figure 2-6. 



□ start Tomcat 




Figure 2-6: 

The Start 
Tomcat 
screen. 




To test that Tomcat is running, open your favorite browser and type the fol- 
lowing URL: 

http : //l ocal host 

If you see the page shown in Figure 2-7, Tomcat is installed and running 
properly 

If the Tomcat home page does not appear, you probably didn't change the 
port to 80 in Step 7 in the "Installing Tomcat under Windows" section. To 
change the port, follow these steps: 

1. Navigate to tomcat-4.1\conf\server.xml. 

2. Open the server, xml Hie with a text editor, such as Notepad. 

3. Use the Find function (in Notepad, choose EditOFind) to find 8080. 

4. Click Find Next to find the next instance of 8080. 

You see the statement port="8080". 

5. Change 8080 to 80. 

6. Save and close the server . xml file. 

7. Restart the Tomcat server. 

8. Try typing http://localhost in your browser again. 
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The default 
Tomcat 
home page. 
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If you're seeing this page via a web browser, it means you've 
setup Tomcat successfully. Congratulations! 

As you may have guessed by now, this is the default Tomcat home 
page, It can be found on the local filesystem at: 

SCATALINA_HOME/ webapps/ ROOT/ index . html 

where "$CATALINA_HOME" is the root of the Tomcat installation 
directory. If you're seeing this page, and you don't think you should be, 
then either you're either a user who has arrived at new installation of 
Tomcat, or you're an administrator who hasn't got his/her setup quite 
right. Providing the latter is the case, please refer to the Tomcat 
Documentation for more detailed setup and administration information 
than is found in the INSTALL file 

NOTE: For security reasons, using the administration webapp is 
restricted to users with role "admin". The manager webapp is 
restricted to users with role "manager". Users are defined in 

$CATALINA_HOME/conf /tomcat-users. xml. 

Included with this release are a host of sample Servlets and JSPs (with 

a=;<;nri afprl t;niirrp rnrlpl pxtpn^ivp rlnn irnpnrstmrr (inrlnrtinn thp 
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Choosing \lour Development Environment 

An integrated development environment (IDE) is a tool for writing and editing 
programming code. However, choosing an IDE is up to you. Some people are 
minimalists and prefer to simply use a good editor. Others like to have every- 
thing built into their development environment. You can find tools out there 
for every taste and budget. 

We like Eclipse (www .eclipse.org). Although Eclipse is definitely not for the 
minimalists, it's not bloated with tons of features you never use. Eclipse has 
all the necessities you might want in a development environment, including 
a great editor, compiler, and debugger. Support for building and deploying 
applications is built-in with the Ant program. 

Ant is a Java-based build tool that makes building and deploying applications 
a one-step process. If you're not familiar with Ant, see ant.apache.org. Like 
Struts, Ant is an Apache open-source project. 

And if Eclipse doesn't offer all the functionality you want or need, chances 
are someone has written a plug-in that does. (A plug-in is a program that pro- 
vides additional functionality and plugs in to the main application.) You can 
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find plug-ins that manage a Tomcat environment, interface with your favorite 
source-code control program, or offer any of a hundred other actions that 
,clipse. Oh, and did we mention that Eclipse is an open-source pro- 
re's no charge for it or most of its plug-ins. 



If you already have a favorite tool and it satisfies your requirements, you 
shouldn't change it. If you do want to try something else but Eclipse is not 
for you, try one of the dozens of Java IDEs available. Some are free and all 
are easy to find on the Internet. Here are a few of the more popular ones: 

V Borland JBuilder: Borland offers Enterprise, Professional, and Personal 
versions of JBuilder. The Personal version is free. Go to www . borl and . 
com/ j bu i 1 der/ index. html . 

IBM WebSphere Studio: Built on Eclipse technology, WebSphere Studio 
expands functionality by combining enterprise-level project management, 
advanced Java development, visual editors, Web infrastructure manage- 
ment, and support for Web services. Visit www -3 . i bm . com/ s of tware/ 
infol/websphere/index.jsp. 

IntelliJ IDEA: This IDE, at www .intellij.com/idea, has received a lot 
of good reviews from developers around the world, so don't ignore it 
when researching your choices. 

NetBeans: Released into open-source in July of 2000 by Sun Microsystems, 
NetBeans at www .netbeans.org,is full-featured and used by many 
developers. 

boWnloadinq and Installing Eclipse 

To download Eclipse, follow these steps: 



1. Go to www. eel i pse. org/ down 1 oads/i ndex. php. 

2. To find the proper download server, click the link for your part of the 
world. 

3. Click the link for the version of Eclipse you want to download. 

The current production version as of this writing is 2.1.2. You see the 
page for the version you chose. 

4. Click the HTTP or FTP link (you can download using either method) 
for your operating system and follow the instructions to complete the 
download. 




If you use plug-ins, be careful about upgrading to the latest and greatest ver- 
sion of Eclipse. Developers sometimes don't update their plug-ins to run with 
the latest Eclipse version for weeks or months after the version release date. 
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To install Eclipse, use a decompression program such as WinZip to extract 
the eel ipse-SDK-2. 1.2-win32.zip file directly to a root of a drive (for 
C:\). An Eclipse folder structure is created automatically. (Don't 
all those files don't go into your root!) 



To run Eclipse, double-click the eclipse, exe file, which is in the Eclipse 
folder that the extraction creates. For further information, read the eel i pse\ 
readme\readme_ecl i pse . html file. For easy access, you probably want to 
create a shortcut to the eel ipse. exe file. 



Getting the Tomcat Launcher 
Plug-in far Eclipse 



If you decide to use Eclipse, you should think about installing at least one 
plug-in that can help you work easily with Tomcat. The Sysdeo Eclipse 
Tomcat Launcher plug-in at www . sysdeo . com/eel i pse/tomcatPl ugi n . 
html is a great addition that has the following features and benefits: 

Lets you start and stop the Tomcat Web container from Eclipse. 

V Lets you register the Tomcat process with the Eclipse debugger. This is 
invaluable when the time comes to test your code running in Tomcat. 

Is free and open source. 

You can read about the other features of the plug-in on the Web site. 

Be sure to install Tomcat, as explained in the "Getting the Web Container" 
section, before installing this plug-in. 

Downloading and installing the 
Tomcat Launcher pluq-in 

To download the Sysdeo Eclipse Tomcat Launcher, follow these steps: 

1. Go to www. sysdeo . com/eel i pse/tomcatPl ugi n. html . 

2. Scroll to the Download section and click the link for the version that 
you want to download. 

You can download the latest version, which may be a beta version, or 
the latest final release. We use version 2.1. 

3. Save the .zip file in any temporary folder or directory. 

4. Make sure Eclipse is not running. 



Part I: Getting to Know Jakarta Struts 



pBocte 



5. Use WinZip or a similar decompression utility to decompress the 
. zi p file. 



mpress the file into theeclipse\plugins folder, assuming that 
i pse is the folder where you installed the Eclipse application. 



Placing the extracted files in the pi ugi ns folder installs the plug-in. 



Configuring the Tomcat Launcher piuq-in 

When you've installed the Tomcat plug-in, you can configure it. 




You must install the Tomcat Web container before you can install the Tomcat 
plug-in. 



Follow these steps to configure the Tomcat plug-in: 

1. Start Eclipse, by double-clicking the eclipse, ex e file or the Eclipse 
shortcut, if you created one. 

2. To activate the plug-in, choose WindowOCustomize Perspective from 
the Eclipse menu. 

The Customize Perspective dialog box opens. Before continuing, be sure 
the current perspective is Java. If it is, the dialog box will have this sen- 
tence across the top — "Select the items to be displayed in the current 
perspective (Java)." 

3. Click the plus sign (+) next to Other, and then click the Tomcat check 
box to select it, as shown in Figure 2-8. Click OK to close the dialog box. 

4. To let the plug-in know where Tomcat is installed, choose WindowO 
Preferences to open the Preferences dialog box. 



E3 Customize Perspective 



Figure 2-8: 

Activating 
the Tomcat 
plug-in in 
Eclipse. 



Select the items to be displayed in the current perspective (Resource). 
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□Java Element Creation 






□Java Navigation 






□Java Open Actions 






□Java Search 






□JUnit 






□ Launch 






□ Resource Navigation 






□ Search 






□ Software Updates 






□Tomcat 
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5. In the list on the left side of the dialog box, click the Tomcat item. 
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the Tomcat Home text box, type the path to the folder where you 
lied Tomcat or click the Browse button to navigate to and select 
older. 



7. At the top of the Preferences dialog box, use the Tomcat Version radio 
buttons to choose the version of Tomcat that you're using, as shown in 
Figure 2-9. 



I Preferences 



(HQ 



Figure 2-9: 

Specifying 
the location 
of the 
Tomcat 
installation. 
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8. To set the SDK's JRE for Eclipse, click the plus sign (+) next to the Java 
item in the list on the left side of the Preferences dialog box. 

9. Click the Installed JREs item and check the panel on the right side of 
the dialog box to make sure that the JRE that's selected is from the SDK. 

You can tell whether the JRE is from the SDK because the location points 
to the path where the SDK was installed. (See Figure 2-10.) The plug-in 
launches Tomcat using the default JRE checked in the Eclipse Preferences 
window. Because Tomcat needs the SDK to perform properly, you need to 
ensure that the private JRE in the SDK is used as the Eclipse default JRE. If 
the JRE is not from the SDK, you need to add the private JRE to the list. To 
add another JRE, see the information after these steps. 




10. To make sure that the plug-in works, click the Start Tomcat button on 
the Eclipse toolbar. 



You see startup messages in the Console window, as shown at the bottom 
of Figure 2-11. 
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Figure 2-10: 

Checking to 
make sure 
that Eclipse 
lists your 
Java SDK 
as the 
default JRE. 
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Figure 2-11: 

Starting 
Tomcat from 
Eclipse. 
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This page will help familiarize you with the Eclipse Workbench. 
To get started, read the sections below and click on the related links. 

@ Installed Features 

To find out more about the features installed in your workbench, choose Help > Welcorn 
and select the feature you are interested in 



■ Console [org apache. catalina. startup. Bootstrap at localhost: 1 4457) 

IHFO: JK2 : ajpl3 listening on /0.a.0.0:BDD9 

3, 2003 2:14:rj0 Ptl org. apache. 3k. server. JKHain start 
INFO: JK running ID=0 time=32/172 conf ig=C : \ Tomcat-4 . 1\ conf \ jlc2 . propertit 



An outline is not available 



i * • a v. x 



Console Tasks 



11. To test Tomcat, open your Internet browser and type http://localhost 
in your browser's address window. 

You see the Tomcat startup page (refer to Figure 2-6). 
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If the JRE you saw listed in Step 9 was not the SDK you installed, follow these 
steps to add another JRE to the list: 



e Preferences dialog box, click the Add button. 

The Create JRE dialog box appears. 

2. In the JRE Name text box, type a name for the new JRE, such as 
SDK 1.4.2. 

3. In the JRE Home Directory text box, type the path where you installed 
the SDK or click the Browse button to navigate to and select the SDK 
directory, as shown in Figure 2-12. 

4. Click OK to save your addition. 

5. In the Installed JREs dialog box, click to select the box next to the JRE 
you just created. 

Refer to Figure 2-10. 

6. Click OK to close the Preferences dialog box. 



Figure 2-12: 

Adding a 
new JRE to 
Eclipse. 
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Zj2sdk1 4 2_03/jre/lib/rt jar 

/j2sdk1 4 2_03/jre/lib/sunrsasign jar 

/j2sdk1.4.2_03/jre/lib/jsse jar 

/j2sdk1.4.2_03/jre/lib/jce.jar 

/j2sdk1.4.2_03/jre/lib/charsets-jar 

Zj2sdk1 4,2_03/jre/lib/ext/dnsnsjar 

/j2sdk1.4.2_03/jre/lib/ext/ldapsec.jar 

/j2sdk1 4 2_03/jre/lib/ext/localedata,jar 

Zj2sdk1 4.2_03/jre/lib/ext/sunjce_provider.jar 



Up 



Add External JARs. 



Use default system libraries 



Getting Stmts 



When you have a fully functioning development environment as well as a 
ready-to-go Web container, you're ready to get Struts and set it up for use. 
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some reason, go to Jakarta, apache, org/ 
struts/acqui ring. html. First click the 
Prerequisites link in the Acquiring Struts section 
to make sure that you have all the prerequisite 
software. Then return to the Acquiring Struts 
section and click the Struts Source Code 
Distribution link to get the source code. 

No prerequisites are required forthe binary ver- 
sion if you're using a Java JRE version 1.4 or 
better. If you intend to use a Java JRE version 



etting the Struts source code 



earlier than 1 .4, you need to get an XML parser. 
Sun Microsystems provides the JXML (Java 
XML) reference (example) implementation at 
java.sun.com/xml, or you can get the 
Xerces XML parser at xml .apache.org. 

Put the parser into the Struts/lib directory after 
installing Struts,. The simplest route is to use the 
latest version of Java (SDK 1.4.2 as of this writ- 
ing), as explained in the "Downloading and 
installing Java" section, earlier in this chapter. 



As of this writing, Struts is in release version 1.1. Although a later version 
might be available by the time you get around to downloading, we suggest 
that you use version 1.1 because this book is based on that version. After you 
feel comfortable with 1.1, you can easily upgrade to the latest version. 



fooWnloadinq Stmts 



The first step in getting started with Struts is to download the code. To down- 
load Struts, follow these steps: 



1. Go to the Jakarta download area at 

j akarta . apache. org/ si te/bi ni ndex. cgi . 

2. Scroll down to the Struts item. 

3. If you're a Windows user, click the 1.1 zip link. If you use Unix, click 
the 1.1 tar.gz link. 

These links are for the binary versions. For the instructions that follow, 
we assume that you download the binary version. 

For an explanation of the KEYS and PGP links that you find on the site, see 
the "Downloading Tomcat to Windows" section earlier in this chapter. 
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Re</ieu/ing the components of Stmts 



ot installed like a regular application — by itself, it's only a frame- 
forms the basis of an application. So the closest step to installing is 
to put the Struts components into their proper positions in the Web applica- 
tion directory structure. We will do this in Chapter 3 when we build our first 
Struts application. 

When you finish downloading the Struts file, decompress it to a temporary 
folder. Navigate to that directory. Inside you see three files and three folders: 

f* I NSTALL: This file outlines special installation notes for Web containers 
other than Tomcat. You can safely ignore this file if you're using the 
Tomcat Web container. 

LICENSE: This file defines the terms by which you can use this software. 

i>* README: This file explains how to install Struts, step by step. You may 
need to refer to the README file if you run into any problems, but the fol- 
lowing sections should be sufficient for most of your purposes. 

contri b/: This folder contains the Struts-EL tag library, which we use to 
build the applications in this book. 

lib/: This folder contains the Struts framework, all the library files 
needed by the framework, and the tag library definitions. 

webapps/: This folder contains documentation and examples of how to 
use the various components of Struts. The documentation and examples 
are in the form of WAR files — compressed Web applications that auto- 
matically expand when you put them into a Web container. 



Libraries 

The libraries we use in the examples in this book are all in the contri b/ 
struts-el/lib folder rather than the 1 i b directory because we use the EL 
version of the tag library. These are all JAR files (Java ARchive), the common 
way to store compressed files in Java. For more information about the EL ver- 
sion of the tag library, see Chapter 1. 



Following are the libraries we use: 



i>* commons beanuti 1 s . jar: Provides various utilities to make working 
with JavaBeans easy. 

commons col 1 ecti ons .jar: Special-purpose implementations of various 
collections not implemented in the standard JDK. 
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*>* commons -di gester . jar: Implements a common mechanism for reading 
and parsing XML files and generating Java objects from the XML. 



ons -f i 1 eupl oad . jar: Implements the functionality that allows 
s to upload files to Web applications. 





commons -1 ang .jar: Provides a host of helper utilities for the java.lang 
API, most notably String manipulation methods, basic numerical meth- 
ods, object reflection, creation and serialization, and System properties. 

The acronym API stands for Application Programming Interface. The API 
specifies the rules by which a programmer can make requests to another 
application. 

V commons -1 oggi ng. jar: Implements the generic logging functionality 
to make use of various logging libraries. 

V commons -val idator.jar: Provides the validation mechanism to vali- 
date user input. 

jakarta -oro . j'ar: Implements regular expressions using the Perl5 
syntax. 

Perl5 is a widely used scripting language for creating Web applications. 
Its implementation of regular expressions is considered the de facto 
standard. 

W j'stl . jar: The first tag library used for the JSP Standard Tag Library 
(JSTL) implementation. 

V standard . jar: The second tag library used for the JSTL implementation. 

struts-el .jar: Implements the standard Struts tag library using the 
Expression Language (EL) defined by JSTL. Only those functions from 
the original tag library that do not have a functional equivalent in JSTL 
are implemented. 

f" struts .jar: Contains all the classes that make up the Struts framework. 

V struts - 1 egacy . jar: Contains references to classes removed from 
Struts 1.1. Used for backward compatibility. 



laq Library Definition 

In addition to the libraries in the preceding list, Struts has a set of standard 
tag libraries that it uses. These libraries are represented by files with . tl d 
extensions. (The tl d stands for Tag Library Definition.) To find more detail 
about tag libraries, see Chapter 10. 



Documentation and examples 

Struts comes with numerous Web applications that provide examples of how 
to use components in the Struts framework as well as documentation on 
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Struts. You can find these examples in the webapps folder. Web applications 
are normally packaged as WAR files (Web ARchive). A WAR file is similar to a 
nd includes all the files that make up your Web application. The Web 
ns that come with a Struts distribution are 



struts blank, war: A starting point to begin your own application. 

i>* struts- document ati on .war: A copy of all the documentation found 
on the Struts Web site. 

i>* strutsexampl e.war: An example application that uses most of the 
features found in Struts. 

]^ strutsexerci setagl i b.war: Test pages for the various tags of the 
standard Struts tag library. 

V struts- up 1 oad .war: An example application that shows how to upload 
files with Struts. 

struts- val i da tor .war: An example application that provides exam- 
ples of how to use the Validator framework. 

ti 1 es documentati on .war: Documentation on how to use tiles. For 
more information on tiles, see Chapter 11. 



Testing \lour Web Application 
Development Environment 

Before starting to use Struts, you need to test all your tools to make sure 
everything works as expected. Don't skip this step: Before you create a Web 
application using Struts (we show you how to create one in Chapter 3), you 
need to be confident that Tomcat runs as you expect it to: 

1. Start Eclipse by double-clicking either the eclipse.exe file or a short- 
cut (if you made one). 

2. If Tomcat is not yet started, start the Tomcat server from Eclipse by 
clicking the Start Tomcat button in the Eclipse toolbar. 

3. Make sure Tomcat is running properly by using your browser to open 
the Tomcat Web page at h ttp : / / 1 oca 1 h os t. 

You should see the Tomcat startup page (refer to Figure 2-6). 

If Tomcat doesn't open properly, make sure that Tomcat was not running 
previously. Click the useful Restart Tomcat button on the Eclipse tool- 
bar. Clicking this button stops Tomcat if it's currently running and then 
starts it again. If Tomcat is not running, clicking the button just starts it. 
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To install your first Web application, the Struts documentation, care- 
fully copy the struts- document ati on .war file from the jakarta- 
uts-l . l\webapps folder to the Tomcat -4 . l\webapps folder. 



cat automatically decompresses and starts the Web application. Is 
the Struts documentation really a Web application? Well, yes, it is. It's 
just not a Struts Web application. However, installing this application 
both tests that Tomcat is working properly and gives you an opportunity 
to look at the Struts documentation. 

5. To test that you have successfully installed the Struts documentation, 
type http://localhost/struts-documentation in your browser. 

You see the page shown in Figure 2-13. From this page, you can find most 
of the documentation found at the Struts Web site. 



Figure 2-13: 

The Struts 
documenta- 
tion page. 
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applications. 



J of this project is to provide an open source framework for building web 



The core of the Struts framework is a flexible control layer based on standaj i techn . /.-.Jie? like Java Servlets, 
JavaBeans. ResourceEundles. and E:rtensibk Markup Language (XML), as well as various Jakarta Commons 
packages. Struts encourages appHc anon, architectures based on the Model 2 approach, a variation of the classic 
Model- View- C pun ollei (MVCj design paradigm. 

Strut; provides its own Contiollei >: omponent and integrates with . the:- ■lini :-l . xn: ? to provide the Model and 
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The Struts framework provides the invisib le underpinning! every professional web application needs to survive. 
Struts helps you create an extensible development environment for your application, based on published 
standards and nr-ver design o.attfirTis 
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6. Copythe struts exampl e. war file from the Jakarta struts- 
1 . l\webapps folder to the Tomcat-4. l\webapps f ol der. 

Tomcat automatically decompresses and starts the Web application. 
This Web application is a Struts Web application. 

7. To test the installation, type http://localhost/struts-example in your 
browser. 
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This sample (shown in Figure 2-14) is an incomplete Struts application that 
allows users to register and maintain a set of mail servers subscriptions so 
can read mail from any subscribed server. Click the A Walking Tour of 
xample Application link to explore the example further. 



Figure 2-14: 

The Struts 
example 
application 
page. 
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Now you have all of the tools you need, installed and in working order, as well 
as the Struts documentation available as a Web application on Tomcat. You 
are finally ready to create your first Web application using Struts — the topic 
of Chapter 3. 
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Application with Struts 



In This Chapter 

Specifying a simple Struts application 
Creating the application structure 
Working with the JavaServer pages 
Adding the formbean 
Creating the JavaBean 
Creating an Action class 
Modifying the configuration files 
Testing the application 



f 

■ n this chapter, you create a simple Struts application from start to finish. 
M This application may seem fairly trivial, but it exposes you to the major 
components involved in a Struts application and gives you an introduction 
to the interaction of these components. We assume that you understand the 
basics of how Struts can create simpler, more flexible, and easier to maintain 
Web applications. If you feel that you need a primer, see Chapter 1. We also 
assume that you have available a complete Web development environment 
on your computer. If not, see Chapter 2 for instructions. 

We start by analyzing the requirements for a Log In application, and then we 
create the application. For each piece of the application, we show you the code 
and then explain the code. Because you already know Java, we emphasize the 
parts of the code that are specific to Struts. Finally, we provide instructions 
for putting the code in its proper place, so that by the end of the chapter you 
have a complete application. 
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application is simple but still provides you with experience with 
Struts. We set certain minimum design specifications to create a Web applica- 
tion based on the Struts framework: 



V At least one View component 

u 0 In the Controller, a subclass of at least one Act i on class that provides 
specific processing functionality for the application 

In the Controller, a subclass of the Acti on Form associated with every 
View component that submits data 

V For the Model, at least one JavaBean to represent the data presented in 
each View 

u 0 For the configuration files, the required updating 

The Login application serves as the entry point to a more complex Music 
Collection application that you build in Chapter 14. By itself, the Login appli- 
cation does nothing of value. However, it provides with a good starting point 
for understanding the development of Struts applications. 

The Login application could be written in a simpler way without using Struts, 
but that would defeat the purpose of explaining the essentials of a Struts 
application without a lot of complications. 



Application requirements 

When you design an application, you need to consider what you need to 
accomplish and assess the requirements. In this case, the requirements for 
a Login application are pretty straightforward, as follows: 

u 0 You want a Log In page that accepts a user's name and password as 
input. 

You want to be able to verify that name and password against a reposi- 
tory of name and password combinations. 

u 0 If the application can verify the user's input against the repository data, 
the application tells the user so by displaying a Success page. 

u 0 If the user's input is rejected, the application tells the user and asks the 
user to try logging in again. 

Now that you have stated the requirements, you can list the steps that you 
need to take to fulfill the requirements of the application. These steps are as 
follows: 
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1. The application displays the Log In page with user name and pass- 
word fields. 
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user types a name and password and clicks the Log In button. 



3. The application checks the submitted values against a repository of 
acceptable values. 

If the name and password are valid (the combination can be found in 
the data repository), the user is forwarded to a Log In Was Successful 
page and a welcome message appears containing the user's name. 

If the name and password are not valid (the combination can't be 
found in the data repository), the Log In page is redisplayed with an 
appropriate error message. 



Determining Which components to use 

In analyzing the requirements, you see that you need not just one View but 
two. Each View requires a JSP page. (For more information on JSP pages in a 
Struts application, see "Creating JavaServer Pages" in Chapter 1.) One JSP 
provides the initial Log In page, and the other JSP is the Successful Log In 
page. The first JSP contains a form that has the username and password 
fields. The second JSP needs only a message indicating that the user has 
logged on successfully. 

For the Controller, you need one specialized Acti on class to handle the 
request from the Log In page and one specialized Acti on Form class to hold 
the request data. 

The Model needs a JavaBean that serves as the data repository. The JavaBean 
contains a list of username and password combinations for authorized users 
and the methods required to operate on that list. 

Finally, to make the necessary connections between the components, you 
need to configure and set up the struts confi g . xml and web . xml files, the 
two principal configuration files for each Struts application, 



Putting Everything in Place 

Now that you know your requirements and the steps to include, you need to 
set up your development environment so that you can work on this project. 
In this example, we use Eclipse and explain step-by-step how to create the ini- 
tial environment for the project. This is not intended to be a tutorial on using 
Eclipse; that task would require another book. However, we do point out the 
minimum set of Eclipse features that you need to initialize, create, build, and 
debug the example applications. 



Part I: Getting to Know Jakarta Struts 




If you're using a different IDE, you need to take similar steps for your IDE. For 
more information on using various IDEs with Struts, see "Choosing Your 
lent Environment" in Chapter 2. 



Creating the project in Eclipse 



When you start to create a program, the first task is to create a project. 
Creating a project specifies the folder that contains all the files for your Web 
application. To create a project, follow these steps: 



1. Start Eclipse. 

For information on starting Eclipse, see "Downloading and Installing 
Eclipse" in Chapter 2. If you're using a different development environ- 
ment, look at the end of this section for instructions on how the final 
application structure should look. 

2. To set up the most appropriate display in Eclipse, choose 
WindowOOpen Perspectives Java. 

Your work area now displays the JAVA perspective and should look like 
Figure 3-1. The Perspectives feature of Eclipse helps customize the dis- 
play for your current needs. For more information, see the "Perspectives 
in Eclipse" sidebar. 



J Welcome x 



Eclipse Platform 



An outline is not 

available. 



[This page will help familiarize you with the Eclipse Workbench. 
To get started, read the sections below and click on the related lin 



-* Installed Features 

To find out more about the features installed in your workbench 
and select the feature you are interested in 

© Perspectives, views and editors 

A window contains one or more perspectives. A perspective co 
and editors for working with your resources. 

The shortcut bar at the far left of the window allows you to oper 
between perspectives that are already open. The perspective y 
is shown in the title of the window and in the shortcut bar as a 



Figure 3-1: 

The Eclipse 
work area 
with the 
JAVA 
perspective. 



© Configuring your perspectives 

You can move views and editors around the workbench by drac 
also add more views to your current perspective by using Wind 
To reset the perspective to its original state, choose Window >\* 
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Perspectives in Eclipse 



fe called perspectives that 
allows you to change the overall arrangement 
of the work area to suit your current task. For 
example, the Java perspective is suited for edit- 
ing and compiling source files. The Java per- 
spective displays various panes called views in 
Eclipse. Do not confuse these views with a View 
in the MVC design pattern. The various views 
show you the project file hierarchy, the source 
code of the file being edited, the output console. 



and an outline of the source file denoting all 
methods and fields of the current source file. 
The perspective can be modified to show dif- 
ferent views depending on your current needs. 
Another perspective is the Debug perspective, 
which displays debugging information about the 
currently running program. This powerful fea- 
ture of Eclipse helps make the developer's task 
easier. 



3. To create a project, choose FileONewOProject. 

The New Project dialog box appears. 

4. In the left pane, click Java from the list of Wizards. In the right pane, 
choose Java Project from the project list. Click Next. 

5. In the Project Name text box, type Login, as shown in Figure 3-2. 

Leave the Use Default check box selected so that the contents of the 
project go into the default c : \ecl i pse\workspace folder. 



3 New Java Project B 

Java Project 

Create a new Java project. 

Project name: J Login| 

Project contents 
W Use default 

Directory | C \eclipse\wc 




Figure 3-2: 

The New 
Java Project 
dialog box. 
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6. Click the Finish button. 

Now you should have a project named Login displayed in the Package 
orer view of the Eclipse window. 



Setting up the application folders 

Now you need to create a folder structure to hold all the files. Part of this 
structure is important only while you're developing your application. The 
other part is important when you're ready to deploy your application to the 
Web container. 



To create the folder structure, follow these steps: 



1. To create a special folder in the project to hold your Java source files, 
right-click the Login project folder item in the Package Explorer view 
and choose NewOSource Folder. 

The New Source Folder dialog box opens. 

2. In the Folder Name text box, type source and click the Finish button. 

3. To add a regular folder to the project, right-click the Login project 
folder item in the Package Explorer view and choose NewOFolder. 

The New Folder dialog box opens. 

4. In the Folder Name text box, type WEB-INF and then click the Finish 
button. 

This is the folder where most of your Web application will reside. For 
more information about the WEB-INF folder and the folder structure for 
Web applications, see the "Web Application Folder Structure" sidebar. 



5. In the Package Explorer view, right-click the W EB I N F folder item and 
choose NewOFolder. 

6. In the Folder Name text box, enter classes and then click the Finish 
button. 

7. Repeat Steps 5 and 6 to add the 1 i b folder in the W EB I N F folder. 

Your folder structure should now look like Figure 3-3. If you're using 
another IDE, create the same folder structure using the tools in your IDE. 



Another entry appears in the Logi n folder: J RE System Library. This 
folder is created automatically when you create your project and contains all 
the Java JAR files needed for a Java project. If the JRE System Library doesn't 
appear, Eclipse may be filtering it from the display. See the next section on 
setting Eclipse filters. 
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eb application folder structure 

ppliWtion has a particular folder 



structure. It starts with the application's folder 
(for example, the Login folder for the Login 
application) and contains at least the WEB - 1 N F 
folder. The WEB- INF folder is required and 
must reside in the root of the Web application's 
folder. 

The WEB -INF folder contains at least two other 
folders, the cl asses and 1 i b folders. All Java 
class files that make up your application as well 
as any property files that the application uses 
reside in the cl asses folder. The 1 i b folder 
contains all the library files, including tag 
libraries, which your application needs. The root 
level of the WEB - INF folder contains all the con- 
figuration files and tag library descriptor files. 



One of the key points about the WEB - INF folder 
is that the Web container hides it. That means 
that as far as the browser is concerned, the 
WEB- 1 NF folder doesn't exist. This is an impor- 
tant security feature. 

Other folders that might be typically found in the 
application folder are folders for organizing 
other files used by the Web pages, such as 
images, JavaScript, CSS (cascading style 
sheets), and applets. All the files in these folders 
are typically meant to be accessible by a 
browser. HTML and JSP pages may or may not 
reside in a separate folder, depending on the 
number of pages that make up the application. 



Figure 3-3: 

The folder 
structure in 
the Package 
Explorer of 
Eclipse. 
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Importing the Stmts files 



int you need to bring the Struts files into your project structure, 
ase, you do the following: 




Import all the library files into the WEB-INF/lib folder. 
Import the tag library description files into the WEB - 1 N F folder. 

You don't absolutely have to import these files, because you're going to inform 
Eclipse about the files in a different but related step. However, having the parts 
to your Web application in the proper folder structure makes it easier to 
deploy the application to Tomcat. 

Library files 

To import the library files, follow these steps: 



1. In the Package Explorer view, right-click the WEBINF/lib folder and 
choose Import. 

The Import dialog box opens. 

2. In the list of import sources, double-click File System. 

3. Click the Browse button next to the From Directory text box and use 
the Import from Directory dialog box to navigate to and select the 

Jakarta - struts -1 . 1/contri b/struts - el / lib folder. Click OK. 

Your folder may be different if you downloaded the Struts files to a dif- 
ferent location. All the .jar files appear in the right-hand pane of the 
Import dialog box. 

4. Select the check boxes of all the .jar files. 

Refer to Figure 3-4. Don't forget to scroll down to display all the .jar 
files. 

5. Click Finish. 



After you've imported the library files, you can see that the Package Explorer 
view is cluttered with the new additions. To hide these library files from the 
view, click the drop-down menu at the top of the Package Explorer view and 
choose Filters. In the Java Element Filters dialog box (see Figure 3-5), scroll to 
the bottom and select the Referenced Libraries items. Click OK. This hides 
from view all libraries referenced by the project. The use of filters is a nice 
way to eliminate clutter. 
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Figure 3-4: 

Importing 
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Tag library description files 

Tciimport the tag library description (. tl d) files, follow these steps: 



e Package Explorer view, right-click the W EB I N F folder and 
choose Import. 

gjtXNG/ The Import dialog box opens. 

You imported the library files into the WEB-INF/lib folder, but the . 1 1 d 
files go into the WEB - 1 N F folder. 

2. In the list of import sources, double-click File System. 

3. Click the Browse button next to the From Directory text box and use 
the Import from Directory dialog box to navigate to and select the 

Jakarta - struts 1 . 1/contri b/struts el / lib folder. Click OK. 

Your folder may be different if you downloaded the Struts files to a dif- 
ferent location. All the . 1 1 d files appear in the right pane of the Import 
dialog box. 

4. Select the check boxes of the following . tl d files, ignoring the others 
because they're not needed for your project: 

• c.tld 

• fmt.tld 

• sql .tld 

• struts-bean-el .tl d 

• struts-html -el .tl d 

• strut s- 1 ogi c-el .tld 

• x.tld 

5. Click Finish. 
Your folder structure should now look like Figure 3-6. 

Configuring Eclipse to use the library files 

Now that you have the .jar files imported to Eclipse, you need to tell Eclipse 
how to find them for compiling. This process is equivalent to putting the files 
on the classpath for the application. 

Classpath and Build Path refer to the same thing: the path or paths used by 
the application to search for certain files (generally Class files). 

To tell Eclipse about the .jar files, follow these steps: 



1. In the Package Explorer view of Eclipse, right-click the project folder 
name (Logi n in our example) and choose Properties. 
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il] Welcome X 



Eclipse Platform 



This page will help familiarize you with the Eclipse Workbench 
To get started, read the sections below and click on the related links. 

? Installed Features 

To find out more about the features installed in your workbench, choose Help > V 
and select the feature you are interested in 

® Perspectives, views and editors 

A window contains one or more perspectives. A perspective consists of views (e.i 
and editors for working with your resources. 

The shortcut bar at the far left of the window allows you to open new perspectives and 
between perspectives that are already open. The perspective you are currently workin 
is shown in the title of the window and in the shortcut bar as a pushed-in icon. 

'-» Configuring your perspectives 

You can move views and editors around the workbench by dragging their titlebars. Yo 
also add more views to your current perspective by using Window > Show View. 
To reset the perspective to its original state, choose Window > Reset Perspective. 

Once you have arranged your perspective, you can save it using Window > Save Pers 
You can customize the views, perspectives and New menu operations that show up ft 
your perspective. To do this choose Window > Customize Perspective. A view car v 



An outline is not available. 



y Tasks (0 items) 



J ! Descriptio 



| Resource | In Folder 



| Location] - 



The Properties for Login dialog box appears. (Login is the name of the 
project in our example. If you named your project differently the dialog 
box uses the name of your project.) 

2. In the list of items in the left pane, choose Java Build Path. 

3. On the right side of the dialog box, click the Libraries tab. 

The dialog box looks like Figure 3-7. 



3 Pr^p^bjs^For J.ogin 



Figure 3-7: 
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dialog box. 



Info 

External Tools Builders 
Java Build Path 

Java Compiler 
Javadoc Location 
Java Task Tags 
Project References 
Tomcat 



Default output folder: 



Java Build Path 

\3 Source | 0 Projects HI Libraries I \\ Order and Export I 


JARs and class folders on the build path: 




+ It JRE System Library [j2re1.4.2_01] 


Add JARs... 


Add External JARs... I 


Add Variable-.. 


Add Library... 


Add Class Folder... 






Edit.., 


Remove 





Part I: Getting to Know Jakarta Struts 



dBooks 

I play< 



4. Click the Add JARs button. 

The JAR Selection dialog box appears. 



Igate to Login/WEB INF/1 ib folder and select all . j a r files dis- 
yed there. Click the Open button. 

All the .jar files are now in the build path of the Login project. You 
need to add one more .jar file to be complete. 

6. Click the Add External JARs button. 

Note that this is the External Jars button. 

7. Navigate to the Tomcat 4 . 1 / common / 1 i b folder, and select the 
servl et . jar file. Click Open. 

The s e r v 1 e t . j a r files adds the all the Java Servlet classes to your build 
path. The Java Servlet classes are necessary because they're not 
included in the Standard Edition of Java (just the J2EE version). The set 
of libraries associated with the project should now look like Figure 3-8. 



Figure 3-8: 

The 
complete 
set of 
libraries for 
the project. 
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Source ] U Projects | Libraries |j Order and Export | 
JARs and class folders on the build path: 
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Wj 0 commons-lang.jar - Login/WEB- INF/lib 
+: 0 comrnons-logging.jar- Login/WEB-INF/lib 
g 0 commons-validator.jar- Login/WEB-INF/lib 
t 0 jakarta-orojar - Login/WEB-INF/lib 
S G jstl.jar- Login/WEB-INF/lib 

* IJH servlet.jar- D:\Tomcat_4.1\common\lib 
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Ei 0 stnjts.jar- Login/WEB-INF/lib 
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Add Class Folder... 



<l 



Default output folder: 



| Login/WEB-INF/classes 



Browse... | 
OK | Cancel | 



8. To close the Properties of Login dialog box, click OK. 

You're now ready to begin creating your JSP pages. 



Chapter 3: Creating a Simple Web Application with Struts 



pB f QQk# 

| Tefore yon move 7TTT, \ 



ownloading the Login project 



Jefore yotTmove on, you might want to down- LoginForm. Java 
load all the code for the Login project to avoid 
having to type it. To get the files, go to 
www.dummies.com/go/jakartaandclick (<" Logi nActi on . java 
the Loqin.zip link. Save Logi n . zi p to a tem- 
porary folder. After the file is downloaded, unzip 
it into a new folder. Login.zip contains the (<" struts-config.xml 
eightfilesthatwe describe in the next sections: 



*<" LoginBean. java 



V* web . xml 



1 ogi n . jsp 
1 oggedi n . jsp 



t>*Appli cat i on Re sources, pro perties 



Creating the JatfaSerVev Pages 

As explained in the "Determining which components to use" section earlier in 
this chapter, the Login application requires two JSP pages. The first is for the 
user to enter the necessary login information, and the second is to notify the 
user that the log-in process was a success. 

For each of the two JSP pages, we show you what the final page will look like 
when the application is complete. Then we list and explain the code. Finally, 
we explain the steps that you need to complete to create the pages. 

In the "Downloading the Login project" sidebar in this chapter, we explain 
how to download all the project files from the For Dummies Web site. So if 
you don't like to type, follow those instructions to avoid typing the files into 
Eclipse manually. 




The to0in.jsp page 

The Login application presents the 1 ogi n . j sp page when the system needs 
to authenticate the user. The 1 ogi n . j sp page has one field for a username 
and one field for a password. The password field displays bullets instead of 
the entered text. The page contains one button to submit the entries to the 
server. Everything is simple and straightforward! 

Figure 3-9 shows what the page will look like. You need to complete several 
more steps before you can display your own 1 o g i n . j s p page, as explained in 
the next sections of this chapter. 
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ting a default editor for JSP files 



You ran sGt fhe~cTetault editor (the editor that 
opens when you double-click the file) for JSP 
pages to be Eclipse's built-in text editor instead 
of the default editor (Wordpad on our system). 
Follow these steps to associate JSP files with 
the Eclipse text editor: 

1. Choose Windows Preferences. 

The Preferences dialog box appears. 

2. In the left pane, double-click the Work- 
bench item. 

3. In the left pane, click File Associations. 

4. In the File Associations pane, click the top 
Add button. 

5. In the New File Type dialog box, type *.jsp 
and then click OK. 



This action adds a new file type, JSP, so that 
we can add an association for it. 

6. In the File Associations pane of the 
Preferences dialog box, be sure that the 
new entry is selected, and then click the 
lower Add button. 

The Editor Selection dialog box appears. 

7. Scroll down and selectthe Text Editor item, 
and then click OK. 

This action associates Eclipse's editor with 
the JSP file type. 

8. Click the OK button in the Preferences 
dialog box. 

Now when you double-click a JSP file in the 
Package Explorer, the Eclipse Text Editor opens 
to edit it. 
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Appearance 
Compare/Patch 

.+ Editors 
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Fonts 
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Figure 3-9: 
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page. 
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The complete code for the login page is in Listing 3-1. The numbers to the left 
of each line are not part of the code. We refer to these numbers when we 
explain the code. 

Listing 3-1 login.jsp 

1 <%@ page contentType="text/html ;charset=UTF-8" language="java" %> 

2 <%-- JSTL tag libs --%> 

3 <%% taglib pref ix="fmt" uri = " /WEB - INF/fmt . tl d " %> 

4 <%-- Struts provided Taglibs --%> 

5 <%@ taglib pref i x=" html " uri="/WEB-INF/struts-html -el .tld" %> 

6 <html : html 1 ocal e=" true" /> 

7 <head> 

8 <fmt : setBundl e basename="ApplicationResources" /> 

9 <title><fmt:message key="login.title"/X/title> 

10 </head> 

11 <body> 

12 <html : errors property="login"/> 

13 <html :form acti on=" 1 ogi n . do" focus="userName"> 

14 <table al i gn="center"> 

15 <tr al ign="center"> 

16 <tdXHlXfmt:message key="login.message"/X/HlX/td> 

17 </tr> 

18 <tr al ign="center"> 
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19 <td> 

<table align="center"> 

<tr> 

<td align="right"> 

23 <fmt: message key="login.username"/> 

24 </td> 

25 <td align="left"> 

26 <html:text property="userName" 

27 size="15" 

28 ^^^^^^^^^^^^ maxlength="15" /> 

29 <html : errors property="userName" /> 

30 </td> 

31 </tr> 

32 <tr> 

33 <td align="right"> 

34 <fmt: message key="login. password"/) 

35 </td> 

36 <td align="left"> 

37 <html rpassword property="password" 

38 size="15" 

39 maxlength="15" 

40 redisplay="false"/> 

41 <html:errors property="password" /> 

42 </td> 

43 </tr> 

44 ^^^^trS^*^ ^"^^^^ 

45 <td colspan="2" al i gn="center"> 

46 <html : submi t> 

47 <fmt:message key="login. button. signon"/) 

48 </html :submit> 

49 </td> 

50 </tr> 

51 </table> 

52 </td> 

53 </tr> 

54 </table> 

55 </html:form> 

56 </body> 
56 </html> 



The first thing to point out is the use of specialized Struts tag libraries. This 
page uses two libraries. The first is a JSTL tag library, f mt, which formats 
data and provides localized message information. The second is a Struts spe- 
cific tag library, struts - html-el, that inserts various HTML elements into 
the page. The other Struts-specific items are on the following lines: 

Lines 3 and 5: Standard JSP directives for including tag libraries in the 
page. The pref i x attribute references the library tags throughout the 
code. 

i>* Line 6: Generates the top-level <html > element and specifies that the 
HTTP header will determine the locale to be used to set the language 
preferences. This tag has implications when you want your Web 
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application to handle more than one language. For more information 
about internationalization (I18N), see Chapter 6. Also see the "Using 



J 8: Identifies to the JSP page the name of the message resource file. 

This tag is from the JSTL f mt tag library. Other ways to identify the mes- 
sage resource file exist, but this method is straightforward. 

f Line 9: Now that the code has identified the message resource file, you 
can reference the key-value pairs in the file. This line is another tag that 
will retrieve the value associated with the key named login-title. That 
value will be displayed as text in the title bar of the browser window. 

;>* Line 12: If the submitted data contains an error, this tag is used to display 
the error. Actually, this tag displays a specific error associated with the 
login property. Any such error is detected by the validation process and 
an error message is generated. (See Chapter 6 for more information on 
validation.) 

Line 13: Generates the html <form> tag. The act i on attribute sets the 
form submission to the URL 1 ogi n . do. Any URL with the . do extension 
is automatically routed to the ActionServlet. We specify the extension 
when we set up the web . xml configuration file towards the end of this 
chapter. The other attribute is focus, which tells the browser in which 
field to put the initial focus. 

Lines 26 and 37: Create the two form fields, userName and password. One 
thing to point out about the password field is the use of the redisplay 
attribute. When this attribute is set to f al se, the value of the password 
field is not redisplayed if the page is redisplayed. This attribute is impor- 
tant for security. Although the password value will contain asterisks if 
the page is redisplayed, the user could view the source code of the page 
to see the full text of password. 

i>* Lines 29 and 41: These error messages are just like the one on line 12, 
except these error messages are specific for each of the fields. If one or 
both of the errors arise, the messages are displayed next to the field in 
which the error occurs. 

The 1 ogi n . jsp file illustrates some of the advantages of Struts applications. 
Error messages generated in the Controller are displayed in appropriate loca- 
tions on the page through the interaction of the struts tag libraries and the 
Controller code. In addition, static text (such as titles, labels, and buttons) is 
never used directly. Instead, Struts inserts the text from a message resource 
file. This eases the job of maintaining JSP pages. 

At this point, if you downloaded the Login project files from the For Dummies 
Web site (see instructions in the preceding section) you can import the login, 
jsp file into Eclipse or you can use the manual method of typing. We have 
instructions for both. 




sage resources" section later in this chapter. 
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Importing (oqin.jsp into Eclipse 

these four steps to import 1 ogi n . jsp into Eclipse: 



e Package Explorer view, right-click the Login project and choose 
Import. 

The Import dialog box appears. 

2. Choose File System and then click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Select the login.jsp check box and then click the Finish button. 



That's all there is to it. 



Entering login.jsp by typing it in 

If you decide to enter the login.jsp file the labor-intensive way, you can 
type login.jsp into the project manually at this point by following these 
steps: 



1. In the Package Explorer View, right-click the Login project and choose 
NewOFile. 

The New File dialog box appears. 

2. In the File Name text box, type login.jsp and then click Finish. 

Because login.jsp is a JSP file and not a Java file, the default editor 
appears unless you have reset the default editor. (See the "Setting a 
default editor for JSP files" sidebar.) 

3. Type Listing 3-1, but do not include the line numbers. 

4. To save your changes, choose FileOSave. 



The loqqedmjsp paqe 

The 1 oggedi n . j sp page is just a validation to the user that the system has 
accepted the username and password combination. This page is even simpler 
that the login.jsp page. The only interesting feature of the page is the inser- 
tion of the user's name in the welcome message. Figure 3-10 shows what the 
page looks like when displayed. 

The complete listing for loggedin.jsp is shown in Listing 3-2. 
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Figure 3-10: 

The 

loggedin.jsp 
page. 
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Welcome, Twinkle Toes. You are now logged in. 



Done 
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Listing 3-2 loggedin.jsp 

1 <%@ page contentType="text/html ;charset=UTF-8" language="java" %> 

2 <%-- JSTL tag libs --%> 

3 <» taglib pref ix="fmt" uri = " /WEB - INF/fmt . tl d" %> 

4 <%-- Struts provided Taglibs --%> 

5 <%@ taglib uri="/WEB-INF/struts-html -el .tld" pref i x=" html " %> 

6 <htm1 : html locale="true"/> 

7 <head> 

8 <fmt:setBundle basename="ApplicationResources" /> 

9 <ti tl eXfmtrmessage key="loggedin.title"/X/title> 

10 </head> 

11 <body> 

12 <H2> 

13 <fmt:message key="l oggedi n .msg"> 

14 <fmt : param value='$(requestScope.userName) ' /> 

15 </fmt:message> 

16 </H2> 

17 </body> 

18 </html> 

This page uses the same two tag libraries as the 1 ogi n . jsp page described 
in the preceding section. The two new things used on this page are both on 
lines 13-15: 
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The message you want to display has a mechanism to accept one or 
more parameters. This is useful when you want to vary the content of a 
sage. The application does not know the user's name in advance but 
s it at runtime. You need to provide that name when the page is run 
so that you can personalize the message to the user. To do so, we add a 
placeholder to the message in the message resource file (see the "Using 
message resources" section later in the chapter): 

1 oggedi n .msg=Wel come , {0). You are now logged in. 

The value has a placeholder { 0 ) that indicates that the first parameter 
that is passed should be substituted for the { 0 ) . Line 14 specifies the 
first and only parameter. 

The logged in.jsp page references values in implicit objects (objects 
already defined by the Web container) using JSTL expression language. 
(See Chapter 10 for more details on JSTL.) In this case, you are using the 
requestScope object, which represents the current request you're pro- 
cessing. In the LoginAction class (we explain the LoginAction class in 
the following section, "Creating an Action"), you specifically put the 
user's name into the request when you validate the user. The user's 
name is referenced by the userName key. So on line 14, you're getting the 
user's name from the request and passing it to 1 oggedi n . msg as the 
first parameter. This personalizes the logged-in message. 

You can enter logged in.jsp into Eclipse by either importing or typing, as 
shown next. 



importing loggedin.jsp into Eclipse 

Follow these four steps to import logged in.jsp into Eclipse: 

1. In the Package Explorer view, right-click the Login project and choose 
Import. 

2. Choose File System and then click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Click the loggedin.jsp check box and then click the Finish button. 



Entering loggedin.jsp bg tgping it in 

Follow these steps to manually enter logged in.jsp into the project: 

1. In the Package Explorer View, right-click the Login project and choose 
NewOFile. 

The New File dialog box appears. 

2. In the File Name text box, type loggedin.jsp and then click Finish. 
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3. Type Listing 3-1 but do not include the line numbers. 
To save your changes, choose FileOSave. 
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Message resources are a means to separate text from the application's code. 
Keeping the text separate from the code makes it easier to change the text 
later, which makes the application easier to maintain. 

One of the key mechanisms to handle I18N is to put any text that will be dis- 
played for the user into a message resource file. The format for this file is 
simply a set of key-value pairs, where the key is used as the reference and the 
value is what is displayed. For example: 

1 ogi n .message=Pl ease Log In! 

In this example, 1 ogi n .message is the key and Please Log I n ! is the value. 
The Login application has a message resource file that contains all the text that 
will be displayed on the two JSP pages. Even if I18N was not a concern (maybe 
your application will be used only internally by your company), using message 
resources is still a good idea. For maintenance, it is generally better not to 
embed static text in your code. By centralizing static text in an external file, 
you can easily make changes to text without disturbing the code. 

In the Login application, the name of the message resource file is 
Appl i cati onResources . properti es. Listing 3-3 shows the key-value pairs 
that the Login application requires. Lines that begin with a number sign (#) 
are comments. 



Listing 3-3 ApplicationResources.properties 

# Resources for Login Project 

# Struts Validator Error Messages 

# These two resources are used by Struts HTML tag library 

# to format messages. In this case we make sure that errors 

# are red so that they can be noticed, 
errors. header=<font color="red">* 
errors. footer=</font> 

terrors associated with the Login page 

error . username . requi red=username is required. 

error . password . requi red=password is required. 

error . 1 ogi n . i nval i d=The system could not verify your username 

or password. Is your CAPS LOCK on? Please try 

agai n . 



#1 ogi n page text 
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1 ogi n . ti tl e=Logi n Project - Log In, Please 
ljogi n .message=Pl ease Log In! 
lt^ii^username=username : 
lp\i^password=p as sword : 
1 ogi n . button . si gnon=Log In 



#1 oggedi n page text 

1 oggedi n . ti tl e=Logi n Project 

1 oggedi n .msg=Wel come , {0). You are now logged in. 



The errors . header and errors . footer are special keys that the html : 
errors tag uses if they are defined. When displaying an error message, the 
html : errors tag will preface the error messages with whatever value is 
associated with the errors, header key. After the error messages are dis- 
played, html : errors displays the value found in the errors . footer key. 

At this point, enter the file into Eclipse using one of the following two methods. 

Importing ApplicationResources.properties into Eclipse 

To import the ApplicationResources.properties file into the project, 
follow these steps: 

1. In the Package Explorer view, right-click the source folder and 
choose Import. 

The Import dialog box appears. 

2. Choose File System and then click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Select the ApplicationResources.properties check box and then click 
the Finish button. 



Entering Application Resources.properties manually into Eclipse 

To enter the Appl i cati onResources . properti es file into the project man- 
ually, follow these steps: 

1. In the Package Explorer view, right-click the source folder and 
choose NewOFile. 

2. In the File Name text box, type ApplicationResources.properties and 
click Finish. 

3. Type Listing 3-3. 

Do not include the line numbers. 

4. To save your changes, choose FileOSave. 
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Any message resource file or other file that you might use needs to be on the 
classpath so that the application can find it. Because the message resource 
ated in the source folder, whenever the project gets rebuilt, it will 
d by the build process to the classes folder. Everything in the 
folder is considered on the classpath. 



Making the Formbean 

The Acti on Form class is part of the Struts Controller. (For more information 
on the Acti on Form class, see the "Struts Controller" section in Chapter 1.) 
The Acti on Form class is associated with a particular View, but could service 
multiple Views, if necessary. Acti on Form is an abstract class, so you always 
use a subclass to create a specific version for your View. 

The main purpose of the ActionForm subclass is to hold the properties of 
the submitted form. Therefore, it has the properties of a JavaBean and is 
called a formbean. You need to reference every form property you need in 
the Acti on Form subclass, such as text fields, radio buttons, and hidden 
properties. In addition, for each property defined, there should be getter and 
setter methods appropriate to Beans. 



Listing 3-4 shows the formbean, Logi n Form . j ava. 
Listing 3-4 LoginForm.java 



1 package dummies. struts; 




2 import javax.servlet.http.HttpServletRequest; 




3 import org. apache. struts. action. ActionError; 

4 import org. apache. struts. action. Acti onErrors ; 

5 import org. apache. struts. action. ActionForm; 

6 import org. apache. struts. action. Acti onMapping; 




7 public class LoginForm extends ActionForm 

8 { 




9 private String userName; 

10 private String password; 




11 public void reset(Acti onMappi ng mapping, HttpServl etRequest request) 

12 ( 

13 password = ""; 

14 userName = " " ; 

15 ) 


16 public ActionErrors validate(ActionMapping mapping, 

HttpServletRequest request) 

17 ( 





Part I: Getting to Know Jakarta Struts 



) < i ) ) 

"error .user name . requi red" ) ) ; 

) < D) 

"error. password. requi red" )) ; 

23 return errors; 

24 ) 

25 public String getPassword( ) ( 

26 return password; 

27 ) 

28 public String getUserName( ) ( 

29 return userName; 

30 ) 



18 Acti onErrors errors = new ActionErrorst ) ; 



p Books 



if((userName == null) || (userName. 1 ength ( 
errors . add ( "userName" , new ActionError( 

21 if((password == null) || (password. 1 ength ( 

22 errors . add ( "password" , new ActionErrort 



31 public void setPassword(String string) { 

32 password = string; 

33 ) 



34 public void setUserName(String string) { 

35 userName = string; 

36 ) 

371 1 



In the example application, you create a subclass of Acti on Form so you can 
create a specific version named Log i n Form. The Log i n Form is tied to the 
1 ogi n . jsp View through the struts-config.xml file (see the section 
"Configuring Struts with struts-config.xml"). The main purpose of Logi n Form 
is to hold the properties of the submitted form. In the case of the 1 o g i n . j s p 
page, you have two fields: the userName and password fields. As a result, the 
associated Logi n Form needs two properties with the same names as the fields, 
as well as the getter and setter methods for those properties. In Listing 3-4, you 
can see the properties in lines 9 and 10 and the getter and setter methods for 
those two properties below line 24. 

Two additional methods can be overridden by the subclass: 

reset method: Can be used to initialize the form's properties (and any- 
thing else you may want) and is called with each new request. In lines 13 
and 14 of Listing 3-4, you set the properties back to the empty string. 

validate method: Is called after theActionServlet populates the 
form with the request properties and before the form is passed to a par- 
ticular Action class for processing. This method is one way that form 
validation can take place to ensure that the user has entered appropri- 
ate and acceptable data. Line 18 creates an empty Acti onErrors object, 
which is the return value for the method. Line 19 and 21 are tests to 
ensure that the user enters something for the userName and password 
fields. If not, the code creates an Acti onError object and adds it to 
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Acti onErrors. Note that when adding Acti onError, the code specifies 
a particular key so that the JSP page will know where to display the 
wtqr. Here is an example from the 1 ogi n . j sp file: 

•Willi :text property="userName" size="15" maxl ength="15" /> 
<html : errors property="userName" /> 

Note that the html :errors tag has a property attribute with the value 
ofuserName, which matches the key associated with the Acti onError 
in line 19. The Acti onError itself is given a message resource key to 
indicate which message should be displayed. 

The validate method is a nice feature of the ActionForm because it provides 
the developer with a way to immediately validate user input. The Struts 
framework will test for errors; if any are detected it redisplays the page with 
appropriate error messages to the user. 

To enter the Logi n Form . j a va file into the project manually, you must create 
the du mm ies. struts package (packages are a way to organize source code 
and the resulting class files into logical units), reset the output folder, and 
then type the source code. These procedures are described in the next three 
sections. 

Creating the packages 

The Log i nForm. Java, Log inAct ion. Java, and Log inBean. Java files need 
to go into the source folder of the project. However, they must be part of the 
du mm ies. struts package, so first create the packages in the source folder. 
To create the dummies and struts packages in the source folder, follow 
these steps: 

1. Open Eclipse or your IDE. 

The instructions that follow are for Eclipse. 

2. Right-click the source folder and choose NewOPackage. 

3. In the Name text box, type dummies. struts. 

4. Click Finish. 

You should now see the package in the source folder. 

5. If you don't see the package, do the following: 

a. Click the Menu down arrow at the upper-right of the Package 
Explorer window and choose Filters. 

b. In the Java Element Filters dialog box, deselect the Empty 
Packages check box. 

c. Click OK. 

The dummi es .struts package should now be visible. 



DropBook 
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Compiling in Eclipse 



ie JavTsource code into class files 
is an automatic process in Eclipse. When you 
save a Java source file, it is automatically com- 
piled into a class file. Compilation errors are 
denoted with a red circle with a white x in the 
center, located in the left margin next to the 
problematic line of code. The class file is saved 



in the default outputfolder. This location can be 
set as a property of the project, as explained in 
the "Setting the default outputfolder" section. 
Syntax checking is performed in real time, as 
you type. Syntax errors are denoted with a red 
line underthe code in question. 



Setting the default output folder 

Before entering any Java source files in Eclipse, set the default output folder 
for the class files toWEB-INF/classes in the Login project. To set the default 
output folder, follow these steps: 

1. In the Package Explorer view, right-click the Login project and choose 
Properties. 

The Properties for Login dialog, box appears. If your project has a differ- 
ent name, your project name appears instead of Login in the name of the 
dialog box. 

2. In the list in the left pane, choose the Java Build Path item. 

3. Click the Source tab. 

4. In the Default Output Folder text box at the bottom of the dialog box, 
type Login/WEB-INF/classes. 

You can also click the Browse button, use the Folder Selection dialog 
box to navigate to the Login/WEB - INF/classes folder, and click OK. 

5. Click the OK button. 

You see the message "The output folder has changed. OK to remove all 
generated resources from '/Login/bin'?". 

6. Go ahead and click the Yes button. 

Now whenever a Java file is compiled, the resulting class file goes in the 
classes folder. This makes it easier to deploy the application. 

Importing the LoqinForm.jatfa file 

To import the Login Form. Java file, follow these steps. 

1. In the Package Explorer view, right-click the dummi es. struts package 
in the source folder and choose Import. 
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2. Choose File System and then click the Next button. 

Click the Browse button next to the From Directory text box and navi- 
to and select the folder where you put the Login files that you 
nloaded. Click OK. 

4. Select the LoginForm.java check box and then click the Finish button. 




Manually entering the LoginForm.ja</a source code 

To manually enter the Logi nForm . j ava file into Eclipse, follow these steps: 

1. In the Package Explorer View, right-click the du mm ies. struts pack- 
age in the source folder and choose NewOClass. 

The New Java Class dialog box appears. 

2. In the Name text box, type LoginForm. 

3. In the Superclass text box, type org.apache.struts.action.ActionForm. 
Refer to Figure 3-11. 

4. Click Finish. 

5. Type Listing 3-4 into the newly created Logi nForm. java file. 
Don't include the line numbers. 

6. To save your changes, choose FileOSave. 



Figure 3-11: 

Use the 
New Java 
Class dialog 
box to 
create the 
LoginForm 
class. 



I New Java Class 



Java Class 

Create a new Java class 



Source Folder: 
Package: 
i Enclosing type: [~~ 



| Login/source 



[* 



umrnies. struts 



Name: 
Modifiers: 



| LoginForm 

public r default 
r abstract r final 



r static 



Which method stubs would you like to create? 

P" public static void main(String[] args) 
r Constructors from superclass 
P Inherited abstract methods 



© 



Superclass: 


org. apache, struts, action. ActionForm 


Browse... 


Interfaces: 




Add... 











Finish 


Cancel 
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Addinaa JaUaBean 

1^ I J ^) ^^tJe^^^Bean represents the Model group and holds the user Name and 
Dassti 



password data for all allowable users. One method validates a particular 
user Name and password combination against the repository of usernames 
and passwords. It's straightforward. In practice, sometimes the Model group 
has a combination of JavaBeans and other classes that go to make up the 
business logic of the application. The JavaBean is shown in Listing 3-5. 



Listing 3-5 LoginBean.java 

package dummies. struts; 

import java.util .HashMap; 

lpublic class LoginBean 
2( 

3 private HashMap validUsers = new HashMapO; 

* Constructor for LoginBean 

* Initializes the list of usernames/passwords 

*/ 

4 public LoginBeanO 

5 I 

6 val idUsers .put( "Twinkle Toes","tt"); 

7 val idUsers.put( "administrator" , "admin" ) ; 

8 validUsers. putt "Barbara Smith", "smitty"); 

9 1 

j** 

* determine if the username/password combination are 

* present in the validUsers repository. 

* @param userName 

* @param password 

* ©return boolean true if valid, false otherwise 
*/ 

10 public boolean validateUsertString userName, String password) 

11 ( 

12 if (val idUsers. contains Key (userName) ) 

13 ( 

14 String thePassword = (Stri ng)val idUsers . get(userName) ; 

15 if (thePassword. equals (password) ) 

16 return true; 

17 ) 

18 return false; 

19 ) 

201 
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The JavaBean has the following noteworthy characteristics: 

J^LiH^s 4-9: The LoginBean constructor creates the data repository as a 
ft^^hMap with the userName as the key and the password as the value. 

V Lines 10-19: The va 1 i dateUser method takes userName and password 
as parameters and then checks to see whether userName is even present 
in HashMap. If not, it returns f al se. If userName is there, it gets the 
password from the HashMap associated with userName (line 14) and 
compares it with the password entered by the user (line 15). If they 
match, the userName and password combination is authenticated and 
the method returns true (line 16). Otherwise, it returns f al se. 

Importing the LoginBean.jaVa fife 

To import the Log inBean. Java file, follow these steps. 

1. In the Package Explorer view, right-click the dummi es .struts package 
in the source folder and choose Import. 

2. Choose File System and then click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Select the LoginBean.java check box and then click the Finish button. 

Manually entering the LoginBean source code 

1. In the Package Explorer View, right-click the du mm ies. struts package 
in the source folder and choose NewC Class. 

The New Java Class dialog box appears. 

2. In the Name text box, type LoginBean. 

3. Leave the Superclass field as-is because you're not creating a subclass. 

4. Click Finish. 

5. Type Listing 3-5 into the newly created Logi nBean . java file. 
Do not include the line numbers. 

6. To save your changes, choose FileOSave. 



Creating an Action 

The Acti on class is called Logi nAct ion. Remember that the purpose of the 
Acti on subclass is to process the user's request. Listing 3-6 creates the 

Logi nActi on class. 
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Listing 3-6 LoginAction.java 
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plckage dummi es .struts ; 



a vax.servlet.http.HttpServlet Request; 
import javax.servlet.http.HttpServletResponse; 



.apache. st ruts. act ion. Act ion; 
.apache. st ruts . acti on. Act i on Err or ; 
. apache, st ruts .act i on. Act i on Errors ; 
.apache, struts .acti on .Acti on Form; 
.apache . struts .acti on .Acti on Forward; 
. apache, struts .acti on. Acti onMapping; 
ass LoginAction extends Action 



import org 
import org 
import org 
import org 
import org 
import org 
lpublic cl 
2( 

3 public Acti onForward execute(Acti onMappi ng mapping, 

4 ActionForm form, 

5 HttpServletRequest request, 

6 HttpServletResponse response) 

7 throws Exception 



// create a new LoginBean with valid users in it 
LoginBean lb = new LoginBeanO; 



// check to see if this user/password combination are valid 

10 i f (1 b. val i da tells er( ( ( Logi n Form) form) .getUserName( ) , 

( ( Logi n Form) form) .get Pas sword ( ) ) ) 

11 { 

12 request .setAttri bute( "user Name" , ( ( Logi n Form) form) .getUserName( ) ) ; 

13 return (mappi ng . fi ndForward( "success" )) ; 

14 1 

15 else // username/password not validated 
( 

// create ActionError and save in the request 

16 ActionErrors errors = new Acti onErrorst ) ; 

17 ActionError error = new Acti onError( "error . 1 ogi n . i nval id" ) ; 

18 errors . add ( "1 ogi n" .error ) ; 

19 saveErrors(request, errors) ; 



20 return (mappi ng.findForwardt "fai 1 ure" )) ; 

21 ) 

22 ) 
23) 



In the Logi nActi on class, note the following items: 



Line 9: Instantiates a LoginBean. (See the "Adding a JavaBean" section 
for the LoginBean description.) The LoginBean represents the Model 
and holds the data regarding authorized users. 

Line 10: Passes userName and password from the Logi nForm to the 
LoginBean's val idateUser method and asks whether the userName 
and password combination is valid. If the code on line 10 returns true 
(the userName and password combination is valid), the code puts the 
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userName into the Request scope for use by the loggedin.jsp page 
on line 12. 



* ' \Swrns control to RequestProcessor. The mappi ng . f i ndForward 
(success) call retrieves the path mapped to the success name. This 
mapping is set up in the strutsconfig.xml file. (See the "Configuring 
Struts" section for details.) 

Lines 16 and 17: If the validation fails, the code creates an 
Acti onErrors object with an error message. 

t<" Line 18: Like the validate method of the Logi nForm class, a key for the 
error is specified when adding the ActionError so that the JSP page 
knows where the error message should be displayed. 

Line 19: Saves the Acti onErrors into the request object using the 
saveErrors method of the Action superclass. 

i>* Line 20: Returns anActionForward object with the real path that's 
mapped to f ai 1 ure; control is then returned to RequestProcessor. 

Notice the minimum dependency between the Controller (Logi nActi on) and 
the Model (Logi nBean) in lines 9 and 10. The code instantiates the Logi nBean 
and then call its val i dateUser method. You have no idea what goes on in the 
Logi nBean and really don't need to care. The Logi nBean could be querying a 
remote database and performing many steps of validation when you call the 
val i dateUser method. This is what MVC is trying to achieve: minimum cou- 
pling (dependencies) between the Model, View, and Controller. With minimum 
dependency, you gain increased flexibility and maintainability in your code. 

Importing the LoqinAction.jaVa file 

To import the Logi nActi on .Java file, follow these steps: 

1. In the Package Explorer view, right-click the dummies.struts package 
in the source folder and choose Import. 

The Import dialog box appears. 

2. Choose File System and click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Select the LoginAction.java check box and click the Finish button. 

Manually entering the LoginAction source code 

If you want to manually enter the code, follow these steps: 




13: Gets anActionForward object for the name success and 



1. In the Package Explorer View, right-click the dummies.struts package 
in the source folder and choose NewO Class. 
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The New Java Class dialog box appears. 
In the Name text box, type LoginAction. 

e Superclass text box, type org.apache. struts. action.Action. 

4. Click Finish. 

5. Type Listing 3-6 into the newly created Logi nActi on . java file. 
Do not include the line numbers. 

6. To save your changes, choose FileOSave. 



Configuring Stmts 



To complete the application, you need to configure the Web container and 
Struts. It is through the configuration files that we tie all the parts together. 
First you configure the Web container so that it knows about the application. 



Defining utebjmt 

Defining the web . xml file makes the Web container aware of your application 
and how to run the application. Listing 3-7 shows the web . xml configuration 
file. 

Listing 3-7 web.xml 

K?xml versi on="l . 0" encodi ng=" I SO-8859 - 1 " ?> 



2<!D0CTYPE web-app 

3 PUBLIC "-//Sun Microsystems, Inc. //DTD Web Application 2.2//EN" 

4 "http: //java .sun.com/j2ee/dtds/web-app_2_2.dtd") 

5<web-app) 



6 

7 <!-- Action Servlet Configuration --> 

8 <servlet> 

9 <servlet-name>action</ servlet -name) 

10 <servlet-class>org.apache.struts.action.ActionServlet 

</servlet-class> 

11 <init-param> 

12 <param-name>conf ig</ pa ram- name) 

13 <param-value>/WEB-INF/struts-config.xml</ pa ram- value) 

14 </init-param> 

15 <1 oad- on -startup>K/l oad- on -startup) 
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16 </servlet> 

!-- Action Servlet Mapping --> 
servl et-mappi ng> 

<servl et-name>acti on</servl et-name> 

20 <url - pa ttern>*.do</url - pattern) 

21 </servlet-mapping> 




22 <!-- The Welcome File List --> 

23 <wel come- f i 1 e-1 i st> ^^^^ 

24 <wel come-f i 1 e>l ogi n . jsp</wel come-f i 1 e> 

25 </wel come-f i 1 e - 1 i st> 



26 <!-- JSTL Tag Library Descriptor --> 

27 <taglib> 

28 <taglib-uri>/WEB-INF/c.tld</taglib-uri> 

29 <taglib-location>/WEB-INF/c.tld</taglib-location> 

30 </taglib> 

31 <taglib> 

32 <taglib-uri>/WEB-INF/fmt.tld</taglib-uri> 

33 <taglib-location>/WEB-INF/fmt.tld</taglib-location> 

34 </taglib> 



35 <taglib> _ 

36 <taglib-uri>/WEB-INF/sql .tld</taglib-uri> 

37 <taglib-location>/WEB-INF/sql .tld</taglib-location> 

38 </taglib> 



39 <taglib> 

40 <taglib-uri>/WEB-INF/x.tld</taglib-uri> 

41 <taglib-location>/WEB-INF/x.tld</taglib-location> 

42 </taglib> 



43 <!-- Struts Tag Library Descriptors --> 

44 <taglib> 

45 <taglib-uri>/WEB- INF/struts -bean-el .tld</taglib-uri> 

46 <tagl i b-1 oca ti on>/ WEB- INF/struts -bean -el .tld</taglib-location> 

47 </taglib> 



48 <taglib> 

49 <tagl i b-uri >/WEB- INF/struts-html -el .tld<7taglib-uri> 

50 <tagl i b-1 oca tion>/WEB- INF/struts -html -el .tld<7taglib-location> 

51 </taglib> 



52 <taglib> 

53 <tagli b-uri >/WEB- INF/struts -logic-el .tld</tagl ib-uri > 

54 <tagl i b-1 ocation>/WEB- INF/struts -logic -el .tld<7taglib-location> 

55 </taglib> 
56</web-app> 
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Here's what you should know about this web . xml file: 

s 8-16: Define the Struts controller, the Acti onServl et. 

9: The ActionServlet is referred to by the name acti on. 

Line 10: Contains the class name. 

V Line 12: Passes one parameter named conf i g to the Servlet. 

i>* Line 13: The value of the parameter is the path to the struts -conf i g . 
xml file). 

v 0 Line 15: Indicates that this Servlet should be the first one to be started 
when the application starts. Right now there's only one Servlet, so the 
order doesn't make much difference. However, when there are many 
Servlets in an application, the starting order is important. 

Lines 18-21: Tell the container that for every URL that the container 
encounters for this application context that ends in . do, it should route 
the request to the acti on Servlet. 

The application context is simply a name used to refer to a particular 
Web application. In our case, the context is Login. 

Lines 23-25: Define the file to display if the user enters the context in 
the browser without specifying a particular file, for example, http : / / 
1 ocal host/Logi n. In this case, the 1 ogi n . jsp page will be displayed 
by default. 

V* Lines 27-42: Define the use of certain JSTL tag libraries and specifies 
where to find the library definition files. The URI in the definition is 
referred to in the JSP file when specifying the use of a tag library. For 
example, the following directive is from a JSP file that specifies the use 
of JSTL's formatting library. Note that the u r i in the directive must 
match the uri defined for the library in the web . xml file on line 32. 

<%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %> 

Lines 44-55: Define the use of certain Struts-EL tag libraries and specifies 
where to find the library definition files. 



Importing uteb.xm( into Eclipse 

Follow these four steps to import web . xml into Eclipse: 

1. In the Package Explorer view, right-click the W EB I N F folder and 
choose Import. 

2. Choose File System and click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 



4. Select the web.xml check box and click the Finish button. 
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Entering the uteb.xni( file into Eclipse 

Tcimanually enter the web . xml file into Eclipse, follow these steps: 



e Package Explorer View, right-click the W E B I N F folder and 
choose NewC File. 

The New File dialog box appears. 

2. In the File Name text box, type web. xml and then click Finish. 

3. Type the text from Listing 3-7. 
Do not include the line numbers. 

4. To save your changes, choose FileOSave. 



Configuring Stmts With stmts-confiqjmt 

You now need to configure Struts with the struts -confi g . xml file. At this 
point, you're going to make the connection between the Views, Forms, and 
Actions. For the Login application you configure three items: the Logi nForm, 
the mapping for the / login path, and the message resource file. Listing 3-8 
shows the struts -confi g . xml file. 



Listing 3-8 struts-config.xml 

K?xml versi on="l . 0" encodi ng=" ISO-8859- 1 " ?> 
2< ! DOCTYPE struts -confi g PUBLIC 

3 "-//Apache Software Foundati on//DTD Struts Configuration 1.1//EN" 

4 "http://jakarta.apache.org/struts/dtds/struts-confi g_l 1 . d t d " > 

5<!-- This is the Struts configuration file for the Login application --> 
6<struts -confi g> 

7 <!-- ========== Form Bean Definitions ================================== --> 

8 <form-beans> 

9 <form-bean name="loginForm" 

10 type="dummi es .struts . Logi nForm"/) 

11 </form-beans> 



12 <!-- ========== Action Mapping Definitions ============================ --> 

13 <acti on-mappi ngs> 

14 <action path="/l ogi n" 

15 type="dummi es . struts . Logi nActi on" 

16 name="l ogi nForm" 

17 scope="request" 

18 input="/login.jsp" 

19 val idate="true"> 

20 <forward name="fai 1 ure" path="/login.jsp"/>21 <forward 

name=" success" path="/l oggedi n. j s p " / > 
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</action> 
acti on-mappings> 



: ======== Message Resources Definitions ======================== --> 

25 <message-resources null="false" 

26 parameter="Appl i cat i on Resources"/) 
27</struts-config> 

Struts -confi g . xml has the following notable lines: 

Line 9: Uses the <form-bean> tag to give LoginForma name you can 
refer to later in the struts confi g file. You must define every form- 
bean that you intend to use in an application, using the <form -beans) 
tag. The Login application has only one formbean, Logi nForm. 

Line 10: Specifies the full class name of the form and closes the tag. 

Line 13: Starts the section on action mappings. The Action Mapping 
Definitions section defines which Acti on subclass should be called when 
a particular path is referenced in a URL. Because you have only one 
Acti on subclass (Logi nActi on), you have only one mapping to define. 

Remember that in the web . xml file we specified, all URLs with a . do 
extension should be routed toActionServlet. Each path defined for an 
action in the struts -confi g file will have the .do extension in the URL. 
The Struts Controller will strip the extension to get the path. That path 
will be used to determine which action should be called. 

i>* Line 14: Begins the one action definition. The path attribute specifies 
which path will result in the Logi nActi on class being called. 

Line 15: Defines the full class name of the Logi nActi on. 

Line 16: Specifies which form-bean should be associated with this 
action. In this case, the code uses the 1 ogi nf orm defined earlier. 

Line 17: Specifies that the scope of the form- bean should be the request 
scope. In other words, where should the form bean exist? The other 
option is the session scope. You would use the session scope if you want 
the form to persist between requests, such as when you have a multi- 
page form. 

V Line 18: Specifies that the login, j sp page populates f ormbean. 

Line 19: Calls the validate method of form bean. Specifying f al se would 
mean not to call the validate method, and validation would need to occur 
through another means. (For more information about other means of vali- 
dation, see Chapter 6). 

is Lines 20 and 21: Contain the actual mapping between a logic name and a 
path. Line 20 specifies the f ai 1 ure name when forwarding to the 1 ogi n . 
jsp page. Line 21 specifies the success name when forwarding to the 
logged in.jsp page. The use of these mappings provides flexibility with- 
out having to change code. You may decide to use a different JSP for 
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success at some point. Rather than having to search your code for all 
instances of / 1 o g g e d i n . j s p and change it to the new JSP, you could 
ly change the path here in the struts-config file. All references to 
e s s in your code would now point to the new JSP rather than the 
old page. Here is a line from LoginAction that shows how the mapping 
is used: 



return (ma pping.fi ndForward( "success" ) ) ; 

0 Line 25: Defines the message resources. Line 25 specifies that the key be 
displayed instead of the value if a key is encountered that can't be found 
in the property file. If you use t r u e instead of f a 1 s e , the behavior will 
be to use an empty string. The parameter attribute defines the name of 
the property file to use for the message resource. It's assumed that the 
file's extension is properties. 

The struts-config.xml file represents the definition of the parts of the 
application to the Struts framework, how the parts are connected with each 
other, and the flow of control. It allows Struts to use your code without you 
having to modify the Struts code directly. This is a big plus in terms of the 
application's flexibility and ease of maintenance. 

Importing struts-config.xml into Eclipse 

Follow these four steps to import struts-config.xml into Eclipse: 

1. In the Package Explorer view, right-click the WEB-INF folder and 
choose Import. 

The Import dialog box appears. 

2. Choose File System and click the Next button. 

3. Click the Browse button next to the From Directory text box and navi- 
gate to and select the folder where you put the Login files that you 
downloaded. Click OK. 

4. Select the struts-config.xml check box and click the Finish button. 
Entering the struts-config.xml file into Eclipse 

To enter the struts-config.xml file into Eclipse manually, follow these steps: 

1. In the Package Explorer view, right-click the WEB-INF folder and 
choose NewC File. 

The New File dialog box appears. 

2. In the File Name text box, type struts-config.xml and then click Finish. 

3. Type Listing 3-8. 

Do not include the line numbers. 

4. To save your changes, choose FileOSave. 
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If you're not using Eclipse as your development 
environment, you still need to follow the basic 
steps as described throughout this chapter. To 
summarize, you need to 

1. Create the folder structure used for a Web 
application. 

2. Put all the JAR and TLD files into the proper 
folders. 

3. Set up your classpath to include all the 
library files described in this chapter. 



Download the Project files from the Web 
site. 

Copy the various project files into the 
proper folders as explained in the "Web 
application folder structure" sidebar. 

Compile the Java source files and put the 
class files into the cl asses folder. 



Now you have the all the files necessary for the project. Your Package 
Manager View should look like Figure 3-12. 

If you're using a development environment other than Eclipse, check out the 
"Creating the project in other development environments" sidebar. 



Figure 3-12: 

The 
Package 
Manager 
after 
importing 
the project 
files. 
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Dropl&QQk&ation 

The time has come to see your Login project in operation. The last step 
before proceeding is to compile the Java source files. Before compiling, 
be sure you have set the default output folder to point toWEB-INF/classes, 
as explained in "Creating the packages" earlier in this chapter. 

To compile your source code, choose ProjectORebuild Project. This command 
generates the class files and puts them in the classes folder, preserving the 
structure of the dummi es/struts package. 

At this point, your folder structure should look like Figure 3-13. If your folder 
structure is different, review the appropriate part of Chapter 3 to see what 
step you missed. Once everything is in place, you can continue here. 



Deploying the Login application 

The folder structure you created for the development process is also the 
structure that the Web container requires for Web applications. Deploying 
the application is just a matter of copying a few files and folders to the 
webapps folder in the Tomcat application folder. To copy the required files 
and folders, follow these steps: 

1. In Windows Explorer, go to the webapps subfolder of your Tomcat 
folder and create a Logi n folder to hold your Web application files. 

2. In Windows Explorer, go to the workspace folder of the Eel i pse 
folder and open the Logi n folder. 

3. In the window with the workspace folder, select the two JSP files and 
the WEB INF folder in the Eel i pse folder and Ctrl-drag to copy (not 
move) them to the Logi n folder in Tomcat 4 . 1 /webapps. 

You have just deployed your application. 



Testing the application 

The Login application is complete, and you should now test it. To test the 
application, follow these steps: 

1. Open Eclipse. 

2. If you're not sure that Tomcat is running, click the Tomcat Restart icon. 
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Figure 3-13: 

The final 
folder 
structure for 
the Login 
project. 
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3. In your favorite Web browser, type the application's URL: http : / / 
1 ocal host/Login. 

(Because the application defines a default page, you do not need to 
enter 1 ogi n . j sp.) You see the login page, as shown in Figure 3-9. 

4. To test the validation process, click the Log In button without entering 
any information,. 

The application should respond with error messages next to both the 
username and password fields, as shown in Figure 3-14. 

5. Try the application again, this time supplying either a password or a 
username, but not both. 

Again, you should see an error message next to the field missing data. 

6. Try logging in with a bad username or password, and then click the 
Log In button. 

This time the error message should appear at the top of the page 
because it is a more general error than the previous ones. 

7. Type a valid username and password (as defined in Log i n Bean) and 
then click Log In. 
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For example, try Twinkle Toes as the username and tt as the password. 
The 1 oggedi n . jsp page should appear (see Figure 3-10) and the user's 
name should be embedded in the message. 

Congratulations on completing your first Struts Web application. 



bebuqqinq With Eclipse 

In Chapter 2 we discussed the Tomcat plug-in for Eclipse and mentioned how 
it registers the Eclipse debugger with Tomcat, allowing you to debug all your 
Web application code from the Eclipse environment. 

It is beyond the scope of this book to describe the Eclipse environment in 
any depth. But let's take a few minutes to explore how you can use the debug- 
ging feature to troubleshoot your Web applications. 

Setting a breakpoint 

You can easily set a breakpoint in your Java source code by double-clicking 
the gray area to the left of the line where you want to stop. To try this out, 
follow these steps: 
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1. In the Package Explorer view in Eclipse, double-click the Logi nActi on . 
java file. 



Logi nActi on. Java file opens in the Eclipse editor. 



set a breakpoint in the first line of the execute method where you 
instantiate a copy of the Logi nBean, double-click the margin to the left 
of that line of code. 

Refer to Figure 3-15. 

Go back to your browser and reenter the http : //l ocal host/ Logi n 
URL to display 1 og i n . j s p again. 

Type an invalid username and password, and then click Log In. 

This action ensures that the Logi nActi on code is executed and that 
you will therefore come to the breakpoint that you just set. 

Return to Eclipse. 

Notice that Perspective has changed from the Java Perspective to the 
Debug Perspective. Eclipse now displays Views that are more appropri- 
ate for the task at hand. 

Use the debugger icons at the top of the Debug View or the equivalent 
menu items in the Run menu to step through your code. 



For further information about debugging under Eclipse, look at the debugging 
topics in Eclipse Help. 



Figure 3-15: 

LoginAction. 
java in 
the Editor 
with the 
breakpoint 
set. 
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In this part . . . 

This is where you delve into the three parts of Struts: 
the Controller, the Model, and the View. Chapter 4 
explains the Controller and how you use it to make your 
Web application execute the business logic that you 
require. Chapter 5 discusses the Model, which represents 
your data. Chapter 6 covers the View, so that your viewers 
can see the results of all your great work. Finally, Chapter 
7 explains the Struts and Web container configuration files 
that you need to use to make sure all the sections of your 
code stay connected. 
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In This Chapter 

Working with the Struts Controller classes 
Understanding the ActionServlet 
Using the RequestProcessor 
Creating the Action classes 



EM/hen you created a Web application using Java in the olden days, you 
WW probably started to write Servlets to service your JSP pages, or in 
Struts terminology, your views. In these enlightened times, you can use the 
Struts Controller classes to help you fly through the development process. In 
this chapter, we explain the Struts Controller classes and show you how they 



can keep you organized. 



Understanding the Stmts 
Controller Classes 

The Struts Controller layer of the MVC design pattern makes up the majority 
of the classes in the Struts framework. This is to be expected because Struts 
is not tied to any particular View or Model implementation. (We explain this in 
more detail in the "How Struts enforces the MVC pattern" section in Chapter 1 .) 
Regarding the View or Model implementation, the Struts architecture is flexible 
and can adapt to many possibilities. Therefore, the emphasis in Struts is in the 
area of implementing the set of classes that go to make up the Controller. 

The Struts Controller contains 41 classes and an additional 17 utility classes 
as of this writing. The principal Controller classes are shown in the UML dia- 
gram in Figure 4-1. (UML stands for Unified Modeling Language and is the 
most common diagramming methodology for software design.) The following 
section provides a brief description of each of the classes. Later in the chap- 
ter, we provide more detail. 



The principal Controller classes are as follows: 
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Acti onServl et: A subclass ofjavax.servlet.http.HttpServlet, 
like most Servlets. The Acti onServl et handles all requests to the 



ts framework whose URL ends in .do. The use of . do to indicate 
Struts should handle the request was defined in the web . xml file we 
create in Chapter 3. 



i>* RequestProcessor: The workhorse of the Controller, whose main func- 
tions are to gather all necessary resources for a request by using the 
configurations in the strutsconfig.xml file and pass control to the 
proper Acti on subclass. 

Acti on: A generic abstract class to handle specific requests from the 
client, that is, the user. You always subclass this class (creating new sub- 
classes such as MyActi onl, MyActi on2, . . . MyActi on/V) for the particu- 
lar needs of the request. 



HttpServlet 



Java Servlet Classes 



Figure 4-1: 

UML 
diagram of 
major Struts 
Controller 
classes. 



RequestProcessor 




ModuleConfic 






> 

















~0~ 



o 



0..* 




PluginConfig 


> 


> 







ActionConfig FormBeanConfig ForwardConfig MessageResourceConfig DataSourceConfig ExceptionConfig 



ActionMapping ActionFormBean ActionForward 



MyActionl MyAction2 MyActionN 



User-defined Classes 



Chapter 4: Controlling with the Controller 



'pBoofcc 



*>* Modul eConf i g: A class containing all the configuration information for 
each module in the application. Much of this configuration information 
presented in the classes that follow. 



onConf i g and Acti onMappi ng: These classes contain all the map- 
ping information needed to map a particular request to a particular 
Action class. Acti onMappi ng extends Acti onConf i g. 

FormBeanConf i g and Acti onFormBean: These classes represent a 
FormBean. Acti onFormBean extends FormBeanConf i g. 

V ForwardConf i g and Acti on Forward: These classes represent destina- 
tions to which an Acti on might direct the RequestProcessor to for- 
ward or redirect a request. Acti onForward extends ForwardConf i g. 
Struts will create an Acti onForward class for each forward definition 
in the struts-conf i g . xml file. 

MessageResourcesConf i g: Represents MessageResources associated 
with a module of a Struts application. For example, in the Login applica- 
tion created in Chapter 3, Message Re sourcesConfig would contain the 
contents of the Appli cat ion Re sources, properties file. 

i>* DataSourceConf i g: Represents datasource elements in the struts- 
con f i g file. DataSources are implementations of the j a v a x . s q 1 . 
DataSource interface that provide database connection management 
and pooling. See Chapter 5 for more information. 

i>* Excepti onConf i g: Represents exception elements in the struts -confi g 
file. An exception element defines how Struts will react to particular types 
of exceptions. 

f" PI ugi nConf i g: Represents plug-in elements in the struts confi g file. 
See Chapter 9 for more information on plug-ins. 



Working With the Master Controller — 
the ActionServlet 

The ActionServlet class is the front-line soldier in the Struts Controller and 
is responsible for handling all requests that come to the Web application. 
Frankly, the Acti onServl et doesn't do very much, but it's still important 
because it is the first to act. 

In this chapter, we mention the classes of the Struts Controller in some detail 
to give you more understanding of their purpose. Because Struts is an open- 
source project, the source code is available to you, the developer, to use as 
needed for the particulars of your application. Therefore, if you need the 
ActionServlet (or any other Struts class) to do something different, you 
simply have to implement a subclass and add the new functionality. 
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Starting the Ser(/tet 



Web container starts, it looks in the web . xml file of each Web appli- 
'is serving and starts the described Servlets in the prescribed order 
as defined in web . xml . Generally, the Acti onServl et is the first Servlet 
started in a Struts application. 

Because the Acti onServl et is just like any other Servlet, it overrides the 
i ni t method of its parent class, HttpServlet. The Web container calls the 
i n i t method to allow the Servlet to initialize whatever resources the Servlet 
needs to run. Acti onServl et does the bulk of its work during this initializa- 
tion phase. This phase creates all the resources needed by the Servlet and 
the modules. 




An application can be made of one or more modules. Each module represents 
a logical set of functionality that together makes the application a whole. 
Smaller applications generally have only one module. (The sample Login 
application in Chapter 3 has just the default module.) But if the project is 
larger, with numerous developers or teams, dividing the application into 
separate modules makes it easier for the different groups to work on the 
application without running into each other. Each module has its own 
struts -confi g . xml file. Acti onServl et must be made aware of additional 
modules. This is accomplished in the Acti onServl et configuration found in 
the web . xml file. For example, if you want to have a separate module named 
purchasing that's configured in its own struts -confi g. xml file, you add 
that information as follows to the web . xml file: 



<servl et . . . > 

<!--default module --> 
<i ni t-param> 

<param-name>config</pa ram-name > 

<param-value>/WEB-INF/struts-config.xml</param-value> 
</init-param> 

< ! - -purchasi ng module --> 
<i ni t-param> 

<param-name>config/purchasing</param-name> 

<param-value>/WEB-INF/struts-config-purch.xml</param-value> 
</init-param> 
</servl et> 



The default module is defined by the strutsconfig.xml file while the 
purchasing module uses the struts -confi g-purch. xml for configuration. 
To switch from one module to another, use the SwitchAction mechanism 
(described later in the chapter) or use the module name in the forward defi- 
nition, as in this example: 



<acti on ... > 

<forward name="success" 

contextRel ati ve="true" 
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path=" /Purchasing/ index. do" 
redi rect="true" /> 

on> 



Following are the major steps that Acti onServl et takes at initialization 
time. These initialization steps are also shown in Figure 4-2. 

1. Creates the message resources used internally by Acti onServl et. 

These are different than the message resources used by each module. 
We discuss message resources briefly in the "Using message resources" 
section of Chapter 3 and discuss them further in Chapter 6. 

2. Defines some of the global characteristics of the application, including 
the location of the struts config.xml file. 

Normally the strutsconfig.xml file is in the WEB - 1 N F folder. However, 
you can define the strutsconfig.xml file to be in some other location. 
You specify this in the web . xml file, which passes the new location as a 
parameter to Acti onServl et. 



Threads and Servlets 



One important aspect of Servlet technology is 
that it creates only one instance of the Servlet. 
Even so, the Servlet can handle multiple requests 
simultaneously because each request is handled 
by an individual thread. A thread is an instance 
of execution of the program's code. Java Serv- 
lets (and any Java class) can support multiple 
threads running simultaneously, which is great 
when you have many people using your Web 
application at the same time. The only catch is 
that you have to write your Servlet code to be 
thread-safe. 

For write thread-safe code, you need to ensure 
that no conflict occurs when multiple clients run 
the code simultaneously. What kind of conflict 
could occur? For example, if you define instance 
or class variables that could be used by a 
method in the class, what happens if two threads 
attempt to modify and then read the same vari- 
able? Let's say that thread 1 modifies instance 
variable x to the value 19 and thread 2 then 
changes the valueto 44. Then thread 1 reads the 



value to perform some additional operation. It 
should read 19 but instead reads 44. Uh oh! Your 
client pays $44 for that $19 tee shirt. The wrong 
result occurs because of this conflict. 

How do you make sure that each thread finds the 
right variable value? In the case of Servlets, you 
just make sure you do not use class or instance 
variables. (The exception would be if the class or 
instance variables were initialized at startup and 
then used in a read-only fashion.) Use only local 
variables in each method because local vari- 
ables are unique for each thread. You can apply 
this method to other classes that you want to 
make thread-safe. Anothertechniqueforthread- 
safety is the use of the synch roni zed key- 
word. See 

Java. sun. com/docs/books/ 

tutorial/essential /threads/ 

to find out more about Java threads, including 

the synchroni zed keyword. 
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In previous versions of Struts, Acti onServl et also set the debug level. 
However, it is now recommended that you set the debug level in the under- 
logging implementation. We talk more about logging in Chapter 13. 




up the Servlet mapping that determines how this ActionServlet 
is accessed. 

This retrieves information from the web . xml file about the name used 
for this Acti onServl et and what URL pattern it handles. These values 
are stored in the Application context, or scope. 

4. Creates the ModuleConfig instance for the first (and possibly only) 
module in the application. 

5. Initializes the message resources for each module. 

Each module can have one or more message resource files defined in 
the Struts configuration file. These files are read into memory during 
initialization. 



Location of the config file 
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Initialize Internal Message Resources 
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URL pattern 



Do for each module in the application: 



Figure 4-2: 

The 

initialization 
process for 
Acti on 
Servi et. 
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Because message resource files are read into memory during initializa- 
tion, any changes that you make to a message resource file after the 
ication starts do not take effect until the next startup. 

alizes the data resources for this module. 

If data resources are defined for your application, they're initialized at 
this step. (See Chapter 5 for more information on data resources.) 

7. Initializes the plug-ins for this module. 

If plug-ins are defined for your application, they're initialized at this step. 
(See Chapter 9 for more information on plug-ins.) 

8. Freezes the configuration for this module. 

The Modul eConf i g object is marked as initialized and nonchangeable. 
Any attempt to change the configuration settings for the Modul eConfig 
object will result in an error. 

9. Repeats Steps 4 through 8 for any additional modules. 



Processing requests 

After Acti onServl et is initialized, it is ready for its main purpose: handling 
user requests. When a request comes in from the client, the Web container 
routes the request toActionServlet. How do you know this? Step 3 in the 
Acti onServ let initialization process, just listed, states that the web . xml file 
defines the URL pattern that this Servlet handles. Any request for the applica- 
tion must have the defined pattern in its URL (usually * . do), and therefore 
the Web container routes the request to the ActionServlet. 

Every request is handled by the process method. The process method first 
adds Modul eConfi g and MessageResources to the request. If the application 
has more than one module, the module's particular Modul eConfig and 
MessageResources are used. Then Acti onServl et gets the Request 
Processor instance for the module being called and calls the process method 
of RequestProcessor, the real workhorse of request processing in Struts. 

That's it. ActionServlet is finished — at least until the next request comes 
in or the container shuts down. 



Shutting dortn the SerViet 

When it's time to shut down the application, the Web container calls 

the Acti onServl et's destroy method to notify Acti onServl et of the 
impending shutdown. This is a standard method of the HttpServl et 
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class that Acti onServl et overrides. During the execution of this method, 
ActionServlet releases any resources generated during the initialization 
module resources, datasource resources, internal message 
, and the logger resource. 



Working vOith the Controller's 
Helper — RequestProcessor 

We've all seen work sites where a bunch of people are digging a ditch. One 
person is standing around watching and making a few comments, while the 
others are down in the hole feverishly digging with their shovels. That's 
the relationship between Acti onServl et and RequestProcessor. Acti on 
Servl et tells RequestProcessor, "dig here," and RequestProcessor does 
most of the work. 

Acti onServl et calls the RequestProcessor's process method to handle the 
incoming request. The process method then performs a series of steps, gath- 
ering resources for the request, calling the specific actions that act on the 
request, and finally forwarding or redirecting the response to the appropriate 
destination. Following are the detailed steps taken by RequestProcessor for 
each request it handles: 

1. Wraps the request in a special wrapper if the request's content type is 

mul ti part /form- data. 

Struts includes a library to provide file upload services. You put that 
library (commons -f i 1 eupl oad . j ar) in the WEB-INF/lib folder. When a 
user uploads a file, the file has a special content type ofmultipart/ 
form-data. When the RequestProcessor finds a request with that 
special type, it puts the request in a special wrapper class so that the 
request can be processed more easily. 

2. Gets the path in order to select the mapping. 

RequestProcessor determines from the request URL the path that 
caused the request and then uses that path in Step 7 to determine which 
Acti onMappi ng to select. 

3. Selects the Local e for the request in the session scope, if configured 
to do so. 

By default, the Loca 1 e of the request is set into the session scope. To 
change it, you would need to specify a different ControllerConfigclass 
in the struts confi g . xml file and set the 1 oca 1 e attribute to f al se. 

A Locale represents a user's language and geographical region. By 
knowing the Locale, the application can customize the language and 
regional formatting for values such as dates and money. 
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4. Sets the content type for the response, if configured to do so in the 

struts-conf ig file. 

:rwise, the content type is the standard text/html . This can be 
ged by specifying a different ControlConfig class and setting the 
content Type attribute to another valid value. 

5. Sets a no-cache header to disallow caching of the page, if configured 
to do so. 

By default, caching is allowed. To disallow caching, you must specify a dif- 
ferent Control 1 erConf i g class and set the noCache attribute to true. 

6. Performs custom preprocessing, if defined in a subclass. 

The processPreprocess method is a hook (an empty method designed 
to be overridden) to allow developers to add custom preprocessing logic 
to each request. To make use of preprocessing, you need to subclass the 
RequestProcessor class and override the processPreprocess method. 
This is described more fully in Chapter 9. 

7. Gets the Acti onMappi ng instance to use. 

Based on the path used for the request, RequestProcessor looks up 
the Acti onMappi ng instance. Acti onMappi ng determines which of the 
Acti on classes to call to process the request. 

8. Checks security roles for this action to make sure that the user can 
perform it. 

The Web container has a built-in security architecture that each applica- 
tion can use. If the application uses the built-in security, the struts- 
conf i g file defines how to use it. This step verifies that the current user 
can perform any specific action. 

9. Gets the Acti onForm instance associated with the request. 

RequestProcessor gets Acti on Form associated with this action based 
onActionMapping.IfActionForm does not yet exist, RequestProcessor 
creates it. 

10. Populates Acti onForm. 

Uses the parameters from the request to populate Acti on Form. 

11. Validates Acti onForm. 

If you're using standard form validation, RequestProcessor calls the 
Act ion Form's validate method now. If validation has any errors, 
RequestProcessor forwards control back to the input form from which 
the request came. 

12. Processes a forward or i ncl ude if specified in Acti onMappi ng. 

If you have used a forward or i ncl ude attribute in the action mapping, 
RequestProcessor processes them at this point. One of these two 
attributes is used if you do not specify an Acti on method to receive 
control. We define these attributes in Chapter 7. 
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13. Calls the execute method on the specific Acti on class. 
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Finally, the Acti on class gets to do its stuff. At this point, the code we 
written to handle this request gets executed. When it is finished, it 
rns an instance of Acti on Forward. 



14. Forwards or redirects to the destination specified by Acti onForward. 

The last step in the request processing is to forward or redirect the user 
to the specified destination, usually a JSP page. 

Each module that the application has defined has one RequestProcessor 
instance. Each RequestProcessor has a reference to Modul eConf i g for that 
module. Figure 4-1 shows the relationship between RequestProcessor and 
ModuleConfig. The ModuleConfig class has all the necessary information 
(mappings, datasources, forwards, exceptions, formbeans, message resources, 
plug-ins, and prefix) to fully describe each module 



Getting DouJn to Work: 
Extending Action Class 

When you start to work with the Action class you have to extend the Struts 
framework to accommodate the particular needs of your application. Action 
Servl et and RequestProcessor can be extended, if you want. But you must 
extend the Action class for two reasons: 



The Acti on class is a Struts class that must be subclassed to be used. 




Acti on subclasses are the only way for you to process a user's request. 
After all, you're the only one who knows how you want to respond to 
your users. 

Acti on subclasses must be thread-safe, as we explain in the "Threads and 
Servlets" sidebar in this chapter, because RequestProcessor creates only 
one instance of each Acti on subclass. If more than one user requests at the 
same time that the same action be performed, the one instance of the Action 
class will be called on to do multiple tasks. Therefore, you must use only local 
variables (class or instance variables that are read-only would also be safe). 



When a request comes in, RequestProcessor needs to know which Action 
subclass should have control. RequestProcessor finds the necessary infor- 
mation from the ActionMapping instance that relates the request URL with a 
particular Acti on class. The Acti onMappi ng instance also indicates which 
Acti on Form should be used with the request. You provide the necessary 
information for Acti onMappi ng when you define the action mappings in the 
struts config file. (See Chapter 7 for more on action mappings.) 
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P r o c e s s o r calls the e x e c u t e method when it is ready to pass control 
ti on class. This method is the principal worker method in the class. 
In the execute method you define all the operations that are necessary to 
handle the request. However, you should not embed all logic in the execute 
method. In fact, if you need to apply some business rules or operations, you 
should create a separate set of business objects. If you follow the MVC model, 
the Model should be responsible for business logic and data manipulation. 
The Controller just makes decisions about the flow of control. 

The Action class can do anything you want it to do. Well, it can't tap dance 
or wear a top hat. Typically, the Acti on class performs the following steps: 



1. Verifies the user. 

If this Acti on is a protected operation (requiring authorization), the 
first thing Acti on should do is to verify the user's authorization. (If 
you're using Web-container-based security, you hand over user verifica- 
tion to the Web container.) Verification could take many forms depend- 
ing on what kind of authorization scheme you use. We talk more about 
security issues in Chapter 12. 

2. Determines which action needs to be performed and performs the 
action. 

If the action is simple and straightforward, you need only one action. 
Sometimes, you may have two or more choices depending on some form 
parameter. For example, you may have a page that displays a list of all 
purchase orders for a particular user. Let's say that the page contains a 
button that enables the user to display the purchase orders for a particu- 
lar date. You have one Acti on class that handles both the initial request 
and subsequent requests for particular purchase orders. In your execute 
method, you need to know whether to display all purchase orders for the 
user or perform a search based on a particular date. Therefore, you need 
to check a form parameter to determine which operation to perform. 

3. Sets or updates the necessary attributes that the destination page 
will need. 

This may mean putting a JavaBean into one of the scopes, or it may 
mean updating a formbean so that when the page is redisplayed it has 
the updated values. 

4. Returns an appropriate Acti onForwa rd object to display the proper 
View. 

The ActionForward object will have all the information needed for the 
RequestProcessor to determine where to forward control. 

Listing 4-1 shows some of the highlights of the Acti on class. Comments 
throughout the listing explain the purpose of the code. 
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piblic class POLi stActi on extends Action 



ic Acti onForward execute(ActionMapping mapping, 
ActionForm form, 
HttpServletRequest request, 
HttpServletResponse response) 

throws Exception 



// Extract attributes we will need from the session 

1 HttpSession session = request . getSessi on( ) ; 
// If validated, user will be in the session 

2 User user = (User) session. getAttribute(Constants. USER_KEY) ; 
// Get the POLi stBean , if it exists 

3 POLi stBean polBean = (POListBean) 

sessi on . getAttri bute( Constants . POLI ST_KEY ) ; 
// ensure user has logged on, otherwise make them 

4 if (user == null ) 
( 

5 return (mapping. findForwardt "1 ogon" )) ; // make user logon 



// ensure we have a POListBean, 

6 if (polBean == null ) 
( 

7 polBean = new POLi stBean ( ) ; 



otherwise create one 



// the action value will determine what we need to do 

8 POListForm polForm = (POListForm) form; 

9 String action = pol Form. getActi on( ) ; 

// if null, first time to the form - just get the user's POs 

10 if ((action == null )) 



11 



pol Bean.fi ndAl 1 (user) ; 



// get all the user's pos 



12 



// Action == Find - do a search 
else if(action.equals("find")) 



// perform the search for the specified purchase orders 

13 polBean. findPurchaseOrders( pol Form. getFi nd( ) , 

pol Form. getFi 1 ter( ) , 
pol Form. getFromt ) , 
pol Form.getTot ) , 
user) ; 

) 

// save the updated bean 

14 session. setAttribute(Constants.POLIST_KEY, polBean); 

15 return (mappi ng . fi ndForwardt "success" )) ; 
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The listing performs the four common steps of the Acti on class, as follows: 
J^Lia^s 1, 2, 4, and 5: Validate the user. 

J"\>s?s 9, 10, and 12: Determine the action to perform and then perform 
that action. 

is Line 14: Sets the attribute that the destination page will need. 

V Line 15: Returns the proper ActionForward object to call the destina- 
tion page. 



Predefined Action classes 

Struts has five predefined Acti on classes for developers to use. Why would 
you want to use these classes? In the appropriate situation, these classes can 
save you a lot of time. These classes are explained in the next few sections. 

ForWardAction 

The ForwardActi on class is useful when you're trying to integrate Struts into 
an existing application that uses Servlets to perform business logic functions. 
You can use this class to take advantage of the Struts controller and its func- 
tionality, without having to rewrite the existing Servlets. Use Forwa rdActi on 
to forward a request to another resource in your application, such as a Servlet 
that already does business logic processing or even another JSP page. By using 
this predefined action, you don't have to write your own Acti on class. You just 
have to set up the struts config file properly to use ForwardActi on. 

The configuration to use ForwardActi on is almost identical to regular Acti on 
class configurations except you use the para meter attribute to specify where 
the request should be forwarded to instead of the forward attribute. The fol- 
lowing code example is from the Struts API documentation: 

<action path="/saveSubscription" 

ty pe= "org. apache. struts. act ions.ForwardAct ion" 

name="subscriptionForm" 

scope=" request" 

i nput=" /subscri pti on . jsp" 

pa ramete r= " /path /to/ process i ng/servl et" /> 

The type attribute is the full class name of the ForwardActi on class. The 
parameter attribute is pointing to the path of the resource you want to for- 
ward control to. The other attributes are like normal acti on definitions. 

IndudeAction 

Like Forwa rdActi on, the I ncl udeActi on class is useful when you want to 
integrate Struts into an application that uses Servlets. Use the IndudeAction 
class to include another resource in the response to the request being 
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processed. All that you have to do is set up the struts-config file properly 
to use I ncl udeActi on, no extension of the class is necessary. The following 
mple is from the Struts API documentation: 



path="/saveSubscription" 
ty pe = "org. apache. struts. act ions.IncludeAct ion" 
name="subscriptionForm" 
scope=" request" 
i nput=" /subscri pti on . jsp" 
para me ter=" /path/to/ i ncl uded/resource" /> 

The type attribute is the full class name of the Incl udeActi on class. The 
parameter attribute is pointing to the path of the resource you want to 
include. The other attributes are like normal acti on definitions. 



SwitchAction 

The Swi tchActi on class provides a means to switch from a resource in one 
module to another resource in a different module. Swi tchActi on is useful only 
if you have multiple modules in your Struts application. The Swi tchActi on 
class can be used as is, without extending. 

To switch to another resource in a different module, set up an a c t i o n path 
using Swi tchActi on in the struts config file, as shown in this code snippet: 

<action path=" /toModul e" 

type = " org. apache. struts. act ions. Swi tchActi on" /> 

Then whenever you want to accomplish a switch, you use the /toModul e 
path in your URL along with two parameters: 

The pref i x parameter indicates which module you want to switch to. 

The page parameter indicates which URL gets control after switching 
modules. 



For example, if you want to switch to the purchasing. do URL in module2, 
your URL might look like this: 

http://localhost/toModule.do?prefi x=/modul e2&page=/ 
purchasi ng . do 

When you switch back to the default module, use an empty string for the 
prefix parameter, as in the following URL: 

http://localhost/toModule.do?prefix=&page=/index.do 



DispatcfiAction 

The DispatchAction class is for developers who want to have numerous 
similar actions in a single Acti on class. You may have a View that offers the 
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user many possible actions to perform. For example, suppose that you have 
a page with a list of purchase orders that the user can sort, void, or print. 

,tions all relate to the list of purchase orders, so you might implement 
cti on class to handle the possible actions. Rather than crowd the 
method with a series of if-then-else statements, you may opt to create 
separate methods that each handle one possible action from the user. The 
DispatchAction class is abstract and must be extended to be used. 




In the purchasing order example, you could create a separate method (sort, 
print, and void) for each of the possible actions. These methods would 
need the same method signature as the standard execute method found in 
the Acti on class. This shows the execute method signature: 

public Acti onForward execute( Acti onMappi ng mapping, 

ActionForm form, 
HttpServl etRequest request, 
HttpServl etResponse response) 
throws Exception 

Your three method signatures would look just like the execute method signa- 
ture, down to the fact that your new methods return an Acti onForward 
object. Following is an example of how to define the sort method signature: 

public Acti onForward sort(Acti onMappi ng mapping, 

ActionForm form, 
HttpServl etRequest request, 
HttpServl etResponse response) 
throws Exception 

When you extend the Di spatchActi on class, do not override the execute 
method. That method is now responsible for calling one of your defined 
action methods. 

The final step is to configure strut conf i g to make use of Di spatchActi on. 
The configuration is just like configuring any action except for the parameter 
attribute. The value of the parameter attribute defines the name of the request 
parameter that will pass along the name of the method to be executed. If you 
want to call the sort method for the pol i st action, you use the following URL: 

http: //local host/my app/poli st. do? me thod=sort 



Here is an example for configuring D i spatchActi on: 

<action path=" /pol i st" 

type="org.example.POListAction" 

name = "pol i stForm" 

scope=" request" 

i nput=" /pol i st . j sp" 

para me ter=" method "/> 
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The type attribute is the full class name of the extended DispatchAction 
class. The parameter attribute names the request parameter method. The 
ributes are like normal acti on definitions. 



LookupDispatchAction 

The predefined LookupDi spatchActi on is similar to Di spatchActi on, in 
that you define in one Acti on multiple methods that handle similar actions. 
The difference between LookupDi spatchActi on and Di spatchActi on is that 
the actual method that gets called in LookupDi spatchActi on isbasedona 
lookup of a key value instead of specifying the method name directly. The 
LookupDi spatchActi on class is abstract and must be extended to be used. 

The entry into the configuration file is similar to Di spatchActi on. The 
parameter attribute contains the name of the request parameter. This time, 
however, the value in the parameter is not a method name but a key used to 
look up the method name: 



<action path="/test" 

type="org.example.MyLookupAction" 
name = " My Form" 
scope=" request" 
i nput=" /test . jsp" 
pa r a mete r=" acti on"/> 



The type attribute is the full class name of the extended LookupDi spatch 
Acti on class. The parameter attribute names the request parameter acti on. 
The remaining attributes are defined like any other standard action definition. 

Because the method to be looked up is based on a key value, LookupDi spatch 
Acti on is more suited to an application that contains multiple submit buttons 
with the same name (but different labels and different actions) on a single 
page, as in the code segment that follows: 

Khtml :f orm acti on=" /test"> 

2 <html : submi t property="acti on"> 

3 <bean :message key="button . add" /> 

4 </html : submi t> 

5 <html : submi t property="acti on"> 

6 <bean :message key="button .del ete"> 

7 </html : submi t> 
8</html :form> 



In this code, all tags are custom tags from the Struts tag libraries. In particular, 
notice that lines 2 and 5 are defining a submit button whose name is acti on. 
Lines 3 and 6 define how the buttons are labeled and also what value is submit- 
ted when the button is clicked. When the form is submitted, action will be a 
request parameter and the button's label will be the value. 
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Assume that the following keys are part of the Appli cat ion Re sources, 
properti es file: 



In this example, if the first button is clicked, the action parameter contains 
the Add Record string. If the second button is clicked, the acti on parameter 
contains Del ete Record. 

You extend LookupDispatchAction in a manner similar to how you extend 

Di spatchActi on: 

f* You do not override the execute method. 

V* You need to create your specialized methods to handle each of the 
actions to be serviced. These methods need to have the same method 
signature as the execute method. 

You must create a protected method named getKeyMethodMap that 
returns a Map. In the implementation of the method, you need to create a 
HashMap and enter key-value pairs. The key corresponds to the keys used 
in defining the buttons on your forms. The value is the name of the associ- 
ated method to invoke. 

The following code shows an example of implementing getKeyMapMethod: 

protected Map getKeyMethodMap( ) 
( 

Map map = new HashMap( ) ; 

map. putt "button . add" , "add"); // add is the method to invoke 
map. putt "button .del ete" , "delete"); // delete is the method to invoke 
return map; 

1 

The following code shows how the add and delete methods would look. Note 
that they return an Acti on Forward object just like the execute method does: 

public Acti onForward add ( Act i onMapping mapping, 
ActionForm form, 
HttpServletRequest request, 
HttpServletResponse response) 
throws IOException, Servl etExcepti on 




.add=Add Record 

. del ete=Del ete Record 



// do add logic here. . . 

return mapping. findForwardt "success" ) ; 



public Acti onForward deletetActionMapping mapping, 
ActionForm form, 
HttpServletRequest request, 
HttpServletResponse response) 
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throws IOException, ServletException 

/ do delete logic here. . . 
eturn mappi ng . f ind Forward ( "success" ) ; 



The final step in understanding how the pieces of the LookupDispatchAction 
puzzle come together is to know that the execute method gets the value of the 
acti on parameter and then uses that value to find the associated key in the 
message resources. After the execute method finds the key, the key is used to 
look up the method name in Map, which the getKeyMethodMap method returned. 
The execute method goes through the following steps: 



1. Gets the name of the parameter that contains the key by looking in 

the Acti onMappi ng. 

This is defined in the preceding action configuration example to be 

acti on. 

2. Gets the value of the acti on parameter from the request. 

In the example, this is either Add Record or Del ete Record. 

3. Using the message resources associated with this application, looks up 
the key for the value retrieved from the acti on parameter. 

In the example, the key could be button .add or button . del ete. 

4. Using the retrieved key, looks up the method name from the Map built 

by getKeyMethodMap. 

In the example, the resulting name isaddordelete. 

5. Calls the method. 



Action Forms 

While the Acti on Form class is part of the Controller, we postpone its discus- 
sion until we talk about Views in Chapter 6. It is the function ofActionForm 
to move information between the View and the Controller. 



Now that you have seen what the Struts Controller does, you can appreciate 
the benefit of using this framework instead of trying to write your own. The 
Struts Controller is an elegant, simple, and extensible design that provides 
maximum flexibility in creating Web applications that cover the gamut of pos- 
sibilities from relatively simple to complex, enterprise level, multideveloper 
products. 
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In This Chapter 

What is the Model? 
Using business objects 
Working with the Model 
Getting a database server 

Using an IDE and Web container with your database server 
Using MySQL 

Connecting the Model to a database 
Using connection pooling 



for those of you who think the Model is related to a fashion show, you're 
in the wrong book. We're talking about the Model part of the MVC design 
pattern. It would be an oversimplification to say that the Model is just about the 
business data. Yet the Model represents the business domain more than the 
View does, and certainly more than the Controller does and typically you use 
the Model in Jakarta Struts to help you connect your Web site with a database. 
In this chapter, we explain how to connect your user with your data. 



Understanding the Model 

The Model holds and manages the business data and all the business func- 
tions related to the data. The Model also provides implementations for 
accessing and modifying the business data that can be invoked by the View 
or the Controller. 

To manage all that data, the Model usually includes at least one instance of 
some persistent data store, most commonly a relational database server. 
However, the Model could interact with many different databases and types of 
data sources anywhere in the world. How the Model represents the business 
data and logic is transparent to the View and the Controller. They don't need 
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to know whether the data resides on the same server as the Web container or 
on another server somewhere in Australia. They need to know only the inter- 
e Model to access the various business functions and data items. 



Just imagine a banking application that allows users to access their banking 
information and withdraw money from thousands of ATMs anywhere in the 
world. Now you have an idea of how complex the Model can become. 

By separating the Model from the View and the Controller, you can share the 
business data and logic across many different applications and different types 
of applications, such as Web applications, client-server applications, and even 
Business-to-Business (B2B) applications. For example, in a B2B application, 
your Model layer may interact with the business functions of another organi- 
zation such as a credit card processing center. This flexibility creates a power- 
ful architecture in which systems can grow and expand with a business — 
you can easily extend and scale systems to accommodate future demands. 

In Chapter 3 we introduce a simple Login application that doesn't even have a 
database, containing just one business object, the Logi nBean. In this chap- 
ter, we enhance the Login application example by connecting it to a database 
as shown in Figure 5-1. 



Figure 5-1: 
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Working With Business Objects 

A business object represents a real-world entity — it can be a person, a place, 
a thing, or a concept. Business objects are taken directly from the business 
domain that you're analyzing. Therefore, not only programmers, but the people 
working in the business departments, can relate to these terms and the ideas 
they represent. In this manner, business objects provide a common ground in 
which developers and domain experts can discuss and define the requirements 
for developing a software application and are the starting point for designing 
any object-oriented system. 
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In object-oriented programming, a developer implements business objects by 
creating classes that hold the data related to a particular business object and 
efining the operations that can be performed on that data, all in one 
ing language structure. In Java, you use either regular JavaBeans 
for simple implementations of business objects or Enterprise JavaBeans (EJB) 
for implementing business objects as distributed components that users can 
access over the network. 



Some good examples of business objects are Customer, Order, and Product. 
Business departments can easily understand these terms, so that these terms 
should definitely become objects in a related software application. The 
Logi nBean from Chapter 3 is not a business object in the sense of represent- 
ing an entity, because it defines a business function performed on a User 
business object. In this chapter, we refine the Login application a little bit to 
better fit the business object definition. 



Meeting requirements for business objects 

Sun Microsystems has defined a set of guidelines for developing enter- 
prise architectures with Java called the J2EE Blueprints (java.sun.com/ 
bl uepri nts). The Enterprise JavaBeans (EJB) technology, which is an ideal 
platform for implementing business objects, addresses all of Sun's require- 
ments. However, not all Web applications are complex enough to justify the 
investment in expertise and money to include an EJB application server. EJB 
is definitely worth investigating further, however, if you plan on taking your 
Struts application to the next level. 

For more information on EJB, read Enterprise JavaBeans For Dummies by Mac 
Rinehart (published by Wiley). Also refer to Java. sun. com/products /ejb. 

In this chapter, we focus on only the following requirements for business 
objects: 

t<" Maintaining state: Retain the value of data between method invocations 
and throughout the process of shutting down and restarting the Web 
application. 

Reusability: A business object is general to the entire business, and you 
should be able to reuse the object in different components of the same 
application or in other applications. For example, an order fulfillment 
application, a customer service application, and a billing application 
could all use the same Customer business object. After you define the 
Customer object, you should not need to reimplement the object in each 
application. 
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In addition to defining business objects that represent real-world entities, you 
need to create additional classes, called helper classes. These classes perform 
the various business functions in the Model layer. 

Helper classes are implementations of objects that you add during the design 
phase. These classes do not directly represent real-world concepts that busi- 
ness people can relate to. Their purpose is to improve the flexibility and struc- 
ture of the programming code. Some examples of helper classes follow: 

u 0 A special data class that holds a set of related data items for the purpose 
of handing it from one subsystem to the next. 

f* A specialized class or set of classes that implements lower-level functions 
for the sake of efficiency. If you tried to implement these functions in the 
business objects, you would end up with bloated classes that would be 
hard to maintain. 

A list of business objects, for the purpose of providing functionality 
related to a set of customers or all customers. 



Uslnq JaVaBeans 

The consensus is that data should be represented as a JavaBean, because 
JavaBeans offer many advantages through their well-defined component 
architecture. The creators of both JSP and the Struts framework made it 
easy to present data that is encapsulated in a JavaBean. Many specialized 
tags and classes help you to extract data from a data object that follows a 
certain naming convention — and following a certain naming convention is 
the hallmark of a JavaBean. 



Implementing the Model 

Struts itself doesn't provide much support for implementing the Model por- 
tion of a Web application, other than the support for datasource implemen- 
tations. In a Struts application, the Acti on classes use JavaBeans to access 
business data or to request the execution of a specific business function. 
That, however, is their only interaction with the Model layer. The underlying 
mechanics of the Model, such as database interactions, data representation, 
and data manipulation, needs to be implemented by you, the developer. 
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e means that the lifetime of the data outlasts the lifetime of the 
on. The data continues to exist after the application or even the 
computer has been shut down. Next time the application starts, the same 
data is still available. We're sure that you don't want your data to disappear 
whenever your users close their browsers. By definition, business objects 
must be persistent. They represent vital business data, such as bank accounts 
and transactions that must be accessible beyond individual invocations of 
the software application. 

You can achieve persistence in many ways, but all approaches result in a 
system that writes the data to some kind of permanent storage device, usu- 
ally a hard drive. 

More often then not, you gain persistence by connecting the Web application 
to a relational database management system (RDBMS). Other alternatives are 
object-oriented databases or file-based repositories. 

Many vendors provide relational database management systems. Some of the 
more popular ones are 

i>* Microsoft SQL Server (www . mi crosof t . com /sql) 

MySQL (www .my sql. com/products /my sql /index. html) 
Oracle (www .oracle.com/ip/deploy/database/oracle9i) 
V Sybase (www . Sybase . com/products) 

MySQL is an open-source implementation of a relational database that is free 
for noncommercial use. We use MySQL in the examples in this chapter. You 
can use any other type of database that you're familiar with, but note that all 
the examples show how to perform certain functions using MySQL. 



Getting MySQL 

To add the capability of persistence to a Struts application, you need the fol- 
lowing items: 

W A relational database management server: We chose MySQL, which is 
open-source and free for noncommercial use. 

v 0 A database driver: A driver is necessary for the Java application to con- 
nect to the database server. The driver is usually a Java class (it can be 
written in another language) that implements the low-level details estab- 
lishing and maintaining connections to a particular database implemen- 
tation. MySQL provides a Java Database Connectivity (JDBC) driver 
called MySQL Connector/J. 
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A database connection pool: In this chapter, we start by using direct 
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JDBC calls to access the database, which works fine for a small Web 
ication. For larger systems, however, this approach could create 
urce conflicts and poor performance. A connection pool that man- 
ages and reuses a certain number of connections to the database server 
is a better solution. At the end of this chapter, we introduce the Jakarta 
Commons Database Connection Pooling (DBCP) implementation. 



Downloading and installing MySQL 

If you want to work through our examples in MySQL, follow these steps to 
download and install the program (on Windows NT, 2000, or XP): 

1. Go to www.mysql . com. 

The various MySQL products are listed on the main page. 

2. Under the Database Server heading, select the Production version, 
which is 4.0.16 as of this writing. 

The MySQL download page appears. 

3. Scroll down until you see all versions listed, ordered by operating 
system. When you find your operating system, click the Download 
link. 

• If the File Download dialog box appears, click the Save button, 
choose a location for the file, and click Save. Remember where you 
put the downloaded file. Then extract the downloaded file to a tem- 
porary folder, using WinZip or some other decompression utility. 

• If the file immediately starts to download and opens in your decom- 
pression application (such as WinZip), extract the files to a tempo- 
rary folder. 

4. Double-click the Setup . exe file and follow the installation instructions. 

By default, MySQL installs in C : \ mysql . You can safely accept all the 
defaults, including the Typical installation option in the Setup Type 
window. 

You've set up your database server. 



Downloading MySQL Connector IJ 

For your Java application to connect to the MySQL database server, you need a 
driver that your program can use. If you're using a database other than MySQL, 
contact your vendor for information on available JDBC drivers. To download 
the MySQL Connector/J to Windows NT, 2000, or XP, follow these steps: 
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1. Go to www.mysql . com. 

Select the Production link for the Connector/J product. 



ion 3.0.9 is the latest version as of this writing. The Connector/J 
download page appears. 

3. Scroll down until you see the Sources and Binaries heading. Click the 
Download link for the zip version. 

• If the File Download dialog box opens, click the Save button, choose 
a location for the file, and then click Save. Remember where you 
put the downloaded file. Then extract the downloaded file to a 
location of your choosing, using WinZip or some other decompres- 
sion utility. 

• If the file immediately starts to download and opens in your decom- 
pression application (such as WinZip), extract the files to a location 
of your choice. 

Next we add this driver to the classpath of Eclipse and Tomcat so that our 
Web application knows where to find it. 



Setting Up \lour IDE and Web Container 

Before you can connect to the database, you need to add the appropriate 
library files to your IDE (if you're using one) and to your Web container. In 
general, you need to take the following steps: 

1. Add the mysql-connector-java-3.0.9-stable-bin.jar file to the 
classpath of your development environment. 

2. Add the mysql-connector-java-3.0.9-stable-bin.jar file to the 
Web container you're using. It should go into the viebapps/yourapp/ 
WEB-INF/1 ib folder. 

If you want to follow along with the example that we presented in Chapter 3, 
you can continue to use Eclipse as your IDE and Tomcat as your Web con- 
tainer and follow the steps in the next two sections. Or you can apply the 
appropriate steps to your own development environment and just read on. 



Importing the class library into Eclipse 

To use the MySQL Connector/J driver in Eclipse, you need to import the 
library file so that you can write and compile code in Eclipse. For more infor- 
mation on using Eclipse, see Chapter 3. 
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t Eclipse. 



t-click the WEB INF/1 1 b folder in the Package Explorer view and 
choose Import. 

The Import dialog box opens. 

3. In the list of import sources, double-click the File System item. 

4. Click the Browse button next to the From Directory text box and 
use the Import from Directory dialog box to navigate to the mysql 
connector- java -3 . 0 .9-stabl e folder. Click OK. 

All the .jar files appear in the right pane of the Import dialog box. 

5. Select the check box for the mysql connec tor- java-3. 0.9 s table- 
bi n . jar file. 

6. Click Finish. 



After you import the .jar file to your IDE, you need to add the file to the 
build path so that your IDE knows that you want to use it during compilation. 
This process is equivalent to putting the files on the classpath for the appli- 
cation. Here we explain how to add the .jar file to the build path in Eclipse: 

1. Right-click the Login project in the Package Explorer view and choose 
Properties. 

2. In the Properties for Login (or your application's name), choose the 
Java Build Path item. 

3. Click the Libraries tab. 

4. Click the Add External JARs button. 

The JAR Selection dialog box appears. 

5. Navigate to the eel i ps e\ works pa ce\Logi n\WEB- INF\1 i b folder. 

6. Select the .jar file you just imported and then click Open. 

7. Click OK. 



Adding the class library to Tomcat 

The preceding set of steps took care of being able to write and compile code 
that accesses the database. To run this code under your Web container, you 
need to copy the class library into your Web container application environment. 
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To copy the class library into the Tomcat Web application environment, 
follow these steps: 



n Windows Explorer. 

In your WEBINFMib folder, select the .jar file that you just imported 
into your IDE. 

To follow along with the example, go to eel i pse\workspace\ Logi n\ 
WEB-INFM ib and select the my sql - connector- Java -3. 0.9 -stable- 
fa i n . j a r file. (Whew! That's a long file name!) 

Copy the my sql- connect or- java-3.0.9stableb in. jar file to the 
WEBINFMib folder of your application in your Web container. 

To follow along with the example, copy the mysqlconnectorjava- 
3.0.9-stable-bin.jar file to the Tomcat\webapps\Login\WEB-INF\ 
lib f ol der. Make sure to press Ctrl as you drag the file so that you 
copy it instead of moving it. 



Working With MySQL 

So far in this chapter, we've explained how to install a database server and 
add some class libraries to your project. These steps are necessary but by 
themselves don't change anything. Before your Web application can connect 
to your database, you need to do the following: 

1. Create a database. 

2. Create at least one table. 

3. Put some data into the table. 

In this section, we use MySQL to explain how to do the following: 

Start the MySQL database server 
Create a database called musiccollection 
v 0 Create a table called users 

Insert three records into the users table 

MySQL provides an implementation of the Structured Query Language (SQL), 
which is an industry standard used by most major RDBMS vendors. (That's 
why the program is called MySQL.) SQL provides commands for creating and 
retrieving data from a relational database. 
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All about SQL 



tarTdnor Structured Query Lan- 
guage, defines a set of commands to manip- 
ulate a relational database system. SQL 
commands can be divided into two main sub- 
languages: 

Data Definition Language (DDL): Used to 
create and destroy databases and data- 
base objects such as tables, fields, and 
indexes. Some of the commands are 

CREATE DATABASE, CREATE TABLE, DROP 
DATABASE, and DROP TABLE. 

Data Manipulation Language (DML): Used 
to create, retrieve, and modify the data in the 
database. Some important commands are 

INSERT, UPDATE, DELETE, and SELECT. 

By the way, the American National Standards 
Institute (ANSI) declared that the correct pro- 
nunciation of SQL is "S-Q-L." However, data- 
base professionals commonly pronounce it 
"see-kwel." We don't care how you say it. 

Although meant to be a standard, each data- 
base vendor implements their own proprietary 
flavor. For example, Oracle uses PL/SQL and 
Microsoft SQL Server uses Transact-SQL. These 
flavors are all based on the industry standard 
ANSI SQL but add certain functions that often 



make some tasks easier. The best practice is to 
not be tempted into using those extensions and 
stick to the ANSI compliant SQL in your appli- 
cations, because that ensures that your appli- 
cations will be portable to other database 
implementations. 

MySQL also has a number of extensions or 
changes to the ANSI standard SQL. However, 
you can run MySQL in ANSI mode by adding the 
- -ansi argument to the command line when 
starting the MySQL server: 

C : \>mysql d-max-nt --ansi 
--standal one 

See the section "Starting and stopping MySQL" 
for more information on starting the MySQL 
server. 

SQL has been around for quite a while, so 
you can find plenty of literature on the Web 
(one such Web site is www . devshed .com/ 
Serve r_Si de/MySQL) as well as a number 
of good books. The MySQL installation includes 
a good tutorial on using MySQL and SQL. If you 
installed MySQL in C:\mysql you can find 
the tutorial at C:\mysql\Docs\manual. 
html#Tutori al . 



Starting and stopping MySQL 

Assuming that you installed MySQL on your C: drive in a folder called mysql , 
open a command prompt window as shown in Figure 5-2 and type the following: 

C : \>cd mysql \bi n 

C:\MYSQL\BIN>mysql d-maxnt -standalone 

The first line changes the current folder to the mysql \bi n folder where all 
the mysql applications reside. The second line starts the MySQL version for 
Windows and specifies that MySQL should not be started as a Windows 
service (- -standal one). 
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databasi 



server. 




You don't see another command prompt because MySQL is still running in 
that command window. That command cursor just keeps blinking until you 
close MySQL. You need to open another command window to give commands 
to MySQL. 

To stop the MySQL server, open another command prompt window as shown 
in Figure 5-3 and type the following: 

C:\MYSQL\BIN>mysql admin shutdown 

In case you were wondering, yes, you do need to open another command 
prompt window. The window in which you started MySQL is not usable, 
because it is waiting for MySQL to quit before it will allow any further com- 
mands to be issued. 



Figure 5-3: 

Shutting 
down the 
MySQL 
database 
server. 
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C:\>cd nysqlNbin 








C:\MVSQL\BIN>roysqladnin shutdown 








C:\MYSQL\BIN> 





















All the MySQL programs are located in the C : \mysql \bi n folder. To avoid 
having to change to that folder each time you want to execute one of those 
commands, you may find it more convenient to add that folder to the system 
path, as follows: 

1. Choose StartCControl Panel. 

If you're using Classic view, choose StartOSettingsOControl Panel 
instead. 

2. Double-click the System icon. 



3. Click the Advanced tab. 
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4. Click the Environment Variables button. 

the System Variables section, select the system variable named Path, 
the Edit button. 

The Edit File System Variable dialog box appears. 

7. Move the cursor to the end of the Variable Value field and type a semi- 
colon (;) and then the path to the MySQL bin folder. 

For example, you might type ;c:\mysql\bin. 

8. Click the OK button three times to close all the dialog boxes and the 
Control Panel. 



Creating * database 

The next step is to create a database in your RDBMS. In this section, we explain 
how to create a database in MySQL. MySQL provides a command-line tool 
for manipulating databases, tables, and data. Open a new command prompt 
window and type the following boldface text to create a database and a table 
as shown in Figure 5-4. (You may need to restart MySQL if you stopped it in the 
preceding section.) 

C : \>cd mysql \bi n 
C:\MYSQL\BIN>mysql 

mysql> create database musi ccol 1 ecti on; 
mysql) show databases; 

When you enter the mysql command, MySQL responds with its own mysql > 
prompt. The next command, create. . . creates an empty database called 
musi ccol lection. We use this name, because in Chapter 14 we describe a 
larger application that manages a collection of music CDs. 



E3J C:\WINDOWS\System32\comman 




Figure 5-4: 

Running 
the MySQL 
command- 
line 
interface. 
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Don't forget the semicolon after each command before pressing the Enter key. 
Otherwise, MySQL will not execute your command because it thinks that you 
continue the command on the next line. This is the default behavior, 
^till type a semicolon on the next line and then press Enter to execute 
your command — a useful technique for entering long commands. 



uinerwise 



After you type the s how databases; command, you see displays a list of 
all databases that exist in this database server. MySQL usually has two 
already called test and mysql . You should also see your newly created musi c 
col 1 ecti on database. 



Your database is not too useful yet. To actually store data in your database, 
you need to create at least one database table. 



Creating a table in MySQL 

After you create a database, you need to create a table. If you're using MySQL 
to create a table in the musiccollection database, type the following at the 
mysql > prompt: 



mysql) use musiccollection; 

mysql) create table users (username varchar(20) , password 

varchar(20) ) ; 
mysql) show tables; 



When you want to execute a command on any of your databases, you always 
need to tell MySQL which database you want to work on. You accomplish this 
with the usemusiccollection command, which switches MySQL to that 
database. All commands entered after the use command perform their task 
on that database. 



The next command creates a simple table called users with two fields, a 
username and a password. The varchar(20) that you see after each field 
name is the data type and size of each field, varchar is a variable-length 
string in MySQL, in this case with a maximum length of 20 characters. 

The show tables command lists all tables in the current database. 



Inserting data in the users table 

The next step is to add data to your table. To add the example data to a table 
in MySQL, type the following at the mysql > prompt, after specifying the data- 
base to use, as explained in the preceding section: 
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rnysql) insert into users (username, password) values 
("admin", "secret"); 
insert into users (username, password) values ("john", 
"dummy" ) ; 

mysqT> insert into users (username, password) values ("barb", 
"struts" ) ; 



The i nsert SQL command allows you to insert data into a table. These 
entries insert three records in the users table with different usernames and 
passwords. 

Note that the commands we explain here are sufficient only for the simplest 
of systems. An industrial-strength application would require you to create 
indexes for better performance, manage users and permissions, create views, 
and so on. In a real-world development team, usually at least one person, des- 
ignated as the database administrator, specializes in designing and tuning the 
database servers. 



Executing queries 

To test that you have created the table and data successfully, you can select 
all the rows in the users table by typing in the following SQL sel ect state- 
ment, after specifying the database to use, as explained in the "Creating a 
table in MySQL" section: 

rnysql) select * from users; 



Using SQL scripts 



You may have noticed by now that typing all 
those commands on the rnysql command line 
is tedious, especially if you make a mistake and 
have to retype your entry. Another approach is 
to write all your SQL commands in a text file and 
then pass the text file to the my sql program. 
MySQL then executes all the commands in that 
file. We provide the SQL forthis chapter in a text 
file at the Jakarta Struts For Dummies\Neb site 
at www. dummies .com /go/ Jakarta. 

To use an SQL script called musi ccol 1 ec- 
ti on . sql, type the following 



C:\>cd rnysql \bin 
C:\MYSQL\BIN>mysql 

< musi ccol 1 ecti on. sql 

The musi ccol 1 ecti on . sql file creates 
the musi ccol 1 ecti on database, which cre- 
ates the table users, and populates the table 
with three records of username and password 
combinations. 

This command assumes that the music 
col 1 ecti on .sql file is located in the same 
folder as the rnysql program. If that is not the 
case, you need to type the full pathname loca- 
tion of the script file on your hard disk. 
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This command displays all records in the users table. The asterisk (*) indi- 
cates that you want to see all fields. You could specify particular field names 
nt to limit the query. For example: 



ect username from users 



shows only the username field but not the passwords field. 

Figure 5-5 shows the command prompt window with the SQL commands dis- 
cussed in the previous few sections. 




Exiting the MySQL command toot 

To exit the MySQL command line tool, type quit or exit at the mysql > 
prompt. MySQL responds, "Bye." You don't have to say "Bye" back, although 
you can if you want. 



Connecting the Model to the Database 

In Chapter 3, for simplicity, we used an example of a JavaBean containing 
hard-coded data. Hard-coding data is not a useful way to implement a Web 
application — or any application for that matter. To make the Login applica- 
tion practical, you need to add a persistent data repository — a database — 
and make LoginBean work with that database. 

To upgrade the Login application, you need to implement a new version of 
the LoginBean. The View and Controller components of this application do 
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not have to change. This gives you a little taste of the power of a layered 
architecture: A change to the Model implementation requires no change in 
layers! 



Working With JDBC 



JDBC stands for Java Database Connectivity and is Java's way of connecting 
to many types of databases. Using JDBC keeps the application code indepen- 
dent of the specific database implementation. 

The JDBC class library is included in the J2SE distribution in the Java . sql 
and j avax . sql packages. The only missing piece is the vendor-specific imple- 
mentation of the Java. sql .Driver interface. These driver classes are avail- 
able for most major database products and act as the connector between 
your application and the database you're using. 

Listing 5-1 shows a modified implementation of Logi nBean using JDBC calls 
to connect to the MySQL database and then query the users table. 



Listing 5-1 LoginBean.java Using JDBC 

I package dummies. struts; 

2 

3 import java. sql .Connection; 

4 import java. sql .DriverManager; 

5 import java. sql .ResultSet; 

6 import java. sql .SQLException; 

7 import java. sql .Statement; 
8 

9 public class Logi nBean 

10 { 

II public boolean validateUser(String username, String password) 

12 ( 

13 boolean valid = false; 

14 Connection con = null ; 

15 Statement stmt = null; 

16 ResultSet rs = nul 1 ; 

17 try 

18 ( 

19 Class. for Name ( "com. my sql . jdbc . Dri ver" ) ; 

20 

21 con = DriverManager. getConnecti on( 

" jdbcrmysql : /71 ocal host7musi ccol 1 ecti on" , "", ""); 

22 

23 stmt = con.createStatementt ) ; 

24 

25 rs = stmt.executeQueryt 

"SELECT * FROM Users " + 

"WHERE username = "' + username + + 

"AND password = "' + password + ); 
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30 



31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 



if (rs.nextO) 
val id = true; 

) 

catch (ClassNotFoundException e) 
e.printStackTracet ) ; 

) 

catch (SQLException e) I 
e . pri ntStackTracet ) ; 



finally 

try 
try 
try 



if (rs != null) rs. closet); ) catch (SQLException e) {); 
if (stmt != null) stmt. closet); ) catch (SQLException e) 
if (con ! = null) con. closet); ) catch (SQLException e) () 



return valid; 



By comparing this code to Listing 3-5 in Chapter 3, you can see that the 
usernames and passwords are no longer hard-coded. Instead, you find JDBC 
calls to connect to the database server and to find the requested username 
in the database. If the username is found and the password matches, the 
validateUsert) method returns true. Let's look at some of these lines in 
more detail: 



Line 19: Loads the appropriate JDBC driver class for this particular data- 
base type. This is the only database-vendor-specific reference. For com- 
plete portability, you would usually store this string in a configuration 
file that you read at startup. 

Line 21: Establishes a connection to the database. This line is equivalent 
to logging into the MySQL database. The first parameter is the connection 
string to the database. The jdbc :mysql : prefix specifies the protocol to 
use (which is JDBC in this case) and the type of data source to access 
(which is MySQL in this example). The rest is the path to the database 
server and the database name. If your database server were on a differ- 
ent machine than your Web application, you would use the IP address 
for the server followed by the database name. 

Note that the last two parameters of Line 21 are empty strings. This is 
where you put the database username and password, respectively, that 
you want to use for the query. You haven't defined any database users 
for your database yet, so at this point anyone can connect. Not very 
secure and not to be imitated in a real application! 

V Line 23: After you acquire a connection, you need to create an SQL state- 
ment, which is an instance of the Java . sql . Statement class. You use 
the statement object to execute an SQL command on the database server. 

Line 25: After the statement has been created, you can execute it by 
invoking the executeQueryt) method and passing it the desired SQL 
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query string. The executeQuery ( ) method returns an object of type 
j ava . sql . Resul tSet , which can hold zero or more rows of data from 
database table that you're querying. 



s 27 and 28: Because the username should be unique in this data- 
base, you can expect at most one row to be returned. If you got one row 
back, the username and password are valid and the validatellserO 
method returns true. 

i>* Lines 37-39: You should always clean up when you're finished. Because 
you created the database connection in this method, you should close 
the connection here as well. 

It is important to close the statement before closing the connection 
because some JDBC drivers will throw an exception if the connection is 
closed and the statement is still open. 



This version of the LoginBeanisa great improvement to the one we used in 
Chapter 3, but it's a bit inefficient. Because the entire code to connect to the 
database is in the validatellserO method, a new connection is created 
every time this method is invoked. This is expensive in terms of computer 
time and resources and can affect server performance when too many users 
are executing queries. 

It would be better to open and the close the database connection outside the 
i nva 1 i dateUser ( ) method and even outside the Logi nBean class. One or 
more connections could be opened when the application starts and then 
reused while the application is running. You could write your own connection- 
pooling mechanism or use one that has already been proven. We look at this 
technique later in this chapter, in the "Pooling Connections" section. 



You can now run the Login application. When you enter the username and 
password, Logi nBean verifies that the entry is valid. 



Retrieving multiple records 

Logi nBean, in line 27 of Listing 5-1, accesses Resul tSet but does not 
retrieve any data. In that case it was not necessary because the users table 
doesn't provide any other fields than the ones we're using in the query. In 
Listing 5-2, we add another method called getAl 1 Users ( ) to the Logi nBean 
class to demonstrate how you can retrieve data from Resul tSet and pass it 
back to the View. We also wanted two more fields — age and status to add 
more personal information about the user. If you want to follow along with 
the example, type the following MySQL commands to add these two fields to 
the database table: 

mysql> alter table users add column age int default 0; 
mysql> alter table users add column status varchar(lO) 
defaul t ' acti ve ' ; 
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The getAl 1 Users ( ) method is shown in Listing 5-2. 
-2 LoginBean.getAIIUsers() 



//...package declaration and other import statements... 

I import java.util . Array List; 

2 

3 public class LoginBean 

4 ( 

5 //... va 1 i dateUser ( ) method ... 

6 

7 /** 

8 * Retrieve a list of all users. 

9 * ©return Array Li st containing a list of Transfer Objects (TO) of type 

10 * UserTO. Returns an empty Array Li st if none where found. 

II */ 

12 public Array Li st getAl 1 Users( ) 

13 ( 

14 Array Li st users = new Array Li st( ) ; 

15 

16 Connecti on con = null; 

17 Statement stmt = null; 

18 Resul tSet rs = null; 

19 try 

20 ( 

// ... database connection code ... 



21 rs = stmt . executeQuery( 

22 "SELECT username, password, age, status " + 
"FROM Users "); 

23 

24 while (rs.nextO) 

25 ( 

26 // Retrieve one user record at a time 

27 String username = rs .getStri ng( 1 ) ; 

28 String password = rs.getString(2) ; 

29 int age = rs .get I nt ( 3 ) ; 

30 String status = rs.getString(4) ; 
31 

32 // Create new user transfer object 

33 UserDTO user = new UserDTO(username, password, age, status); 
34 
35 

36 
37 
38 
39 

// ... catch and finally blocks ... 



// Add user to list of users 
users. add(user) ; 

1 



40 return users; 

41 ) 

42 } 
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-to-relational mapping frameworks 



ie"pTobTBrn orsnJfing objects in a relational 
database is similarto putting a square peg in a 
round hole. They just don't match. Data belong- 
ing to an object is determined in part by the rela- 
tionships the object has with other objects in 
the hierarchy of objects. On the other hand, in a 
relational database, you relate data by provid- 
ing a common field among tables of data. 

When making an object persistent by storing its 
data in a relational database, the commontech- 
nique isto combine the hierarchy into one table. 
Therefore, the superclass may be duplicated in 
many tables. Another approach is to break the 
data out of each class of objects and insert the 
data into a separate table. 

Likewise, when reconstituting the objects from 
table data, the programmer must know how the 
relationships are defined in the database table 
and reconstruct the objects based on a series 
of queries. 

Don't you wish you could just use an object- 
oriented database instead?Then you would not 
have these problems because both the applica- 
tion code and the database would support the 
object-oriented paradigm. However, at the pre- 
sent time, relational databases are still more 
widely used and accepted. It may be a few 



more years before OODBMS (Object Orientated 
Database Management System) will rival 
RDBMS. 

In the Logi nBean example, we had to do the 
mapping between the users table and 
UserDTO ourselves. That wasn't too bad, but 
what if you have many database tables and 
more complex objects that have many relation- 
ships to other objects. Implementing the map- 
ping logic would become quite a task. 

Well, there's good news: Object-to-relational 
mapping (ORM) frameworks strive to solve this 
mismatch issue. ORMs are tools that do the 
mapping for you. Some create Java classes that 
you can use to access the database. Others use 
XML definitions of your business objects to map 
them to the database structure. 

You can map your Java objects to relational 
database tables using several expensive ORM 
as well as a few free ones. You might want to 
investigate the following free ones: 

Object Relational Bridge (OJB) at db. 

apache . org/ojb 

Castoratcastor.exolab.org 
Expressoatwww.jcorporate.com 



The following lines are of interest: 

]S Line 1: Because you're retrieving not just one record but potentially 
many, you need to use a collection class from the Java class library 
called Array Li st to hold the row data. 

i>* Line 12: The getAl 1 Users ( ) method returns an object of type Array Li st 
containing all the user records. 

V Line 22: The sel ect statement now lists the names of the fields that you 
want to retrieve instead of just using an asterisk to get all fields. In this 
way, you can match each field in Resul tSet to a particular field in the 
database. 
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Line 24: Uses a for loop to cycle through the result set. With each itera- 
tion, you retrieve one row from the users table. 

s 27-30: For each row, the code first assigns the value of each field 
separate variable. The Resul tSet class provides getter methods 
to retrieve values of various data types. Most of the fields are of type 
Stri ng, so the code uses the getStri ng( ) method. However, the age 
field is an integer, so it uses the get I nt ( ) method. 

These getter methods take care of the type casting for you, but if you 
use the wrong method, you'll get a runtime exception. Notice that each 
method takes a number as an argument. The number signifies the order 
of the fields as shown in the sel ect statement. Another version of each 
getter method allows you to pass the field name, for example, getString 
("username"). However, using numbers to specify fields is generally 
recommended. If the field name changes in the database, you would 
have one less place where you have to modify your code to accommo- 
date that change. 

f Line 33: Creates a user Data Transfer Object (DTO), as shown in Listing 5-3. 
A DTO is a design pattern that helps improve performance and keep the 
data structures used in the persistence layer hidden from the business 
logic and presentation layers. The object-oriented paradigm encourages 
many calls to get various data items from an object. However, that is 
inefficient when accessing a relational database because each method 
call translates to a network transaction. Hence, the code uses transfer 
objects to retrieve all the data for an object at once and then package it 
into a DTO before passing it back to the other layers. 

Line 36: Each user DTO that you create must be added to Array Li st. 

Line 40: Finally, you return the list of user objects. You could write 
another Controller action to use the getAl 1 Users ( ) method and then 
display the results in another JSP page. 



Listing 5-3 UserDTO.java 

1 package dummies. struts; 
2 

3 import java.io.Serializable; 
4 

* User Transfer Object (TO). Previously called Value Object (VO) 

* or sometimes Data Transfer Object (DTO). 
*/ 

5 public class UserDTO implements Serializable 

6 I 

7 private String username = null; 

8 private String password = null; 

9 private i nt age = 0; 

10 private String status = null; 



(continued) 
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blic UserDTO(String username, String password, int age, String status) 



14 this. username = username; 

15 this. password = password; 

16 this. age = age; 

17 this. status = status; 

18 ) 
19 

20 public String getUsernamet ) ( 

21 return username; 

22 ) 
23 

24 public String getPasswordt ) ( 

25 return password; 

26 ) 
27 

28 publ i c i nt getAget ) ( 

29 return age; 

30 ) 
31 

32 public String getStatusO ( 

33 return status; 

34 ) 

35 ) 

For more information on JDBC, see Sun's JDBC home page at Java . sun . com/ 
products/ jdbc and Sun's Java Tutorial Trail on JDBC Database Access at 
j ava. sun. com /docs/books/tutor ial/jdbc/index. html. 



Pooling Connections 

Creating and removing a connection to a data source is an expensive proposi- 
tion in terms of time and computer resources. Therefore, you should try to 
minimize these operations to keep data-access processing efficient. So some- 
one cleverly asked, "Why not keep a collection of live connections hanging 
around, and when a request for a database access comes up, just give the 
requester one of the live connections from the pool? When the requester has 
completed the database request, the connection goes back into the pool for 
someone else to use." 

In JDBC 2.0, a definition for a connection pooling interface was added, but an 
implementation was not included. Instead of writing your own implementa- 
tion, you can use one provided by a vendor. We use the implementation of 
the Jakarta Commons DBCP project. 
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Jakarta Commons DBCP 




rta Commons DBCP (database connection pooling) project provides 
fn'iiftp^Wfmentation of the JDBC 2.0 connection pool specification. 

Jakarta Commons DBCP is built on another project, the Jakarta Commons 
Pool. The Jakarta Commons Pool implements a general object pooling mecha- 
nism that can pool any kind of object. Commons DBCP reuses this generalized 
object pooling implementation to provide a data source connection pooling 
mechanism. 

Each project has its respective home page, where you can find more informa- 
tion on what the project is and how to use it. Those home pages are Jakarta, 
apache . org/commons/dbcp/ and Jakarta. apache . org/commons/pool /. 
However, you can also go directly to the Jakarta Binary Downloads Page to 
download these — and all other Jakarta projects. 

To download Jakarta Commons DBCP and Pool for Windows NT, 2000, or XP, 
follow these steps: 

1. Go to ja ka rta . apache . org/si te/bi ni ndex. cgi . 

2. Scroll down to the Commons DBCP entry, and click its 1.1. zip link. 

• If the File Download dialog box appears, click the Save button, 
choose a location for the file, and click Save. Remember where you 
put the downloaded file. Then use WinZip or some other decom- 
pression program to unzip the file to a location of your choosing. 

• If the file immediately begins to download and WinZip or another 
decompression program opens with the files, extract the files to a 
location of your choosing. 

3. Go to ja ka rta . apache .org/si te/bi ni ndex. cgi . 

4. Scroll down to the Commons Pool entry and click its 1.1. zip link. 

• If the File Download dialog box appears, click the Save button, 
choose a location for the file, and click Save. Remember where you 
put the downloaded file. Then use WinZip or some other decom- 
pression program to unzip the file to the root of a drive. 

• If the file immediately begins to download and WinZip or another 
decompression program opens with the files, extract the files to a 
location of your choosing. 

5. Add the DBCP class library, commons dbcpl.l.jar, and the Pool 
class library, commons pool 1 . 1 . j a r , to both Eclipse and Tomcat. 

See the "Setting Up Your IDE and Web Container" section, earlier in this 
chapter, for instructions. 
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The implementation class for the connection pool we use is called Basic 
DataSource. An older implementation called Generi cDataSource, is now 
^■delseca^c/ (outdated) and will be removed from Struts 1.2. However, Struts 
\J* |^|i^^ferences the Generi cDataSource class, even when you use 

Basi cDataSource. 

When running your Web application, the first time you make a reference to 
the datasource you'll get a runtime error message. The message will say that 
Struts can't find the Generi cDataSource class. To remedy this, make sure 
you're including the struts-legacy, jar class library file to your Eclipse 
and Tomcat setup. You can find this library file in the jakartastrutsl.l/ 
1 i b folder. 



Using connection pooling 

Listing 5-4 shows the example LoginBean rewritten to make use of the con- 
nection pooling capability. 

Listing 5-4 LoginBean.java 

I package dummies. struts; 
2 

3 import java.sql .Connection; 

4 import java.sql .ResultSet; 

5 import java.sql . SQLExcepti on ; 

6 import java.sql .Statement; 
7 

8 import javax.sql .DataSource; 

9 

10 public class LoginBean 

II { 

12 private DataSource dataSource = null; 

13 

14 public LoginBeanCDataSource dataSource) 

15 { 

16 this. dataSource = dataSource; 
} 

18 

19 public boolean validateUser(String username, String password) 

20 ( 

21 boolean valid = false; 
22 

23 Connection con = null ; 

24 Statement stmt = null; 

25 ResultSet rs = null ; 

26 try 

27 ( 

28 con = dataSource. getConnectionO; 
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33 



stmt = con.createStatementt ) ; 

rs = stmt . executeQuery( 

"SELECT * FROM Users " + 



34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 



' " + username + " ' 
+ password + ) ; 



"WHERE username = 
"AND password = ' 

if (rs.nextO) 
val id - true; 

) 

catchtSQLException e) { 
e.printStackTrace( ) ; 



finally ( 

try { if (rs != null) rs. closet); ) catch (SQLException e) I); 
try { if (stmt != null) stmt. closet); ) catch (SQLException e) {); 
try { if (con != null) con. closet); ) catch (SQLException e) {); 

) 

return valid; 



The only new lines in this code are the ones in bold. They replace the more 
tedious way of connecting using a driver manager. Also, this class no longer 
contains any data-source-specific code, making it more general and reusable. 
Also note the following: 



Line 8: Note that import java.sql .DriverManagerisno longer there. 
Instead, we now import the javax.sql .DataSource class. 

V Lines 14-17: The Logi nBean class no longer creates the connection 
itself. Instead, at construction time, a reference to a DataSource object 
is passed to the Logi nBean class, which stores it in an i nstance vari- 
able on line 12. 

Line 28: The only thing to do to acquire a database connection is to call 

getConnecti on ( ) on the DataSource object. 



For the connection pooling to work, you have to make a change to the 
Logi nActi on class. In Eclipse, locate the Logi nActi on . j ava file. Look for 
the line: 



LoginBean lb = new LoginBeant); 
Change this line to look like the following: 



LoginBean lb = new Logi nBean (getDataSourcet request , 
"musiccol lection" ) ) ; 



This change takes care of passing a DataSource object reference to 

Logi nBean. 
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Configuring the data source in Struts 



to make one more change and that is to register the data source in 
s configuration file, struts-config.xml, which is located in the 
WEB- INF folder. 

Add the data source definition as shown in lines 2 through 15 of Listing 5-5 to 
the beginning of the struts-config.xml file, just after the first element in 
the file, <struts-config>. 



Listing 5-5 struts-config.xml Data Source Definition 

1 <struts-conf i g> 

2 <!-- ========== Data Source Definitions ================================ 

> 

3 <data-sources> 

4 <data-source key="musi ccol 1 ecti on" 

5 type=" org. apache. commons. dbcp.BasicDataSource") 

6 <set-property property="descri pti on" value="Music Collection 

Database"/) 

<set-property property="dri verCl assName" val ue="com.mysql .jdbc. Driver"/) 

8 <set-property property="username" 
val ue="theDatabasellserNatne" /> 

9 <set-property property="password" 
\ia]ue=" theDatabasellser Password" /> 

10 <set-property property="url " 

11 val ue=" jdbc: mysql ://l ocal host/musi ccol 1 ecti on"/) 

12 <set-property property="maxCount" val ue="8"/> 

13 <set-property property="mi nCount" va 1 ue=" 2 " /> 

14 </data-source> 

15 </data-sources> 

</struts-conf i g> 

Within the < d a t a - s o u r c e s > element, you can define as many data sources as 
you want. To access them, you use the key parameter for the <data source> 
element. Notice in lines 8 and 9 that you need to replace theDatabaseUserName 
and theDatabaseUserPassword with the appropriate values for connecting to 
your own database. 

When requesting a data source in your web application's Act i on classes, you 
can use the provided getDataSourceC ) method. The method takes two argu- 
ments, the request object and a key string: 

getDataSourceC request, "musi ccol 1 ecti on" ) ; 

This method call returns a reference to the data source we defined in Listing 
5-5. You could now add additional data-source declarations with different 
keys and then access each as you need it. This procedure makes managing 
multiple data sources and connection pools easy. 
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After you update the strutsconfig.xml filein your workspace, make sure 
you copy this file to the Tomcat webapps\Logi n\WEB- INF folder. 

^^jf^^^r you change an application configuration file (web . xml , struts - 

conf i g . xml , or any of the property files), you need to restart Tomcat before 
the changes can take place. 



That's all you have to do. You can run your application again. However, as a 
user, you won't notice any difference. As a developer, you can rest assured 
that your Struts application will be able to handle a much greater load while 
still performing well. 

For more information on configuring a data source in Struts, look at the 
Struts online documentation at the following address: 

Jakarta. apache. org/struts/userGuide/configurati on. 
html #data -source_conf i g 
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In This Chapter 

Choosing a View technology 

Creating applications for an international audience 

Connecting the View and the Controller 

Using the DynaActi on Form class for automation 



Mi you want your application's users to see your beautiful work, you need to 
M create a visual component for your application. In the Struts implementa- 
tion of the MVC pattern, you have complete flexibility to choose the View tech- 
nology of your choice. After you choose a technology you need to implement 
it. In this chapter, we discuss some View options, how to create applications 
for an international clientele, and how to connect the View to the Controller. 



Choosing JSP or an Alternative 



Struts doesn't care what View architecture you choose to use. Most develop- 
ers use the JSP architecture, but this is not a requirement. However, Struts 
does distribute a comprehensive tag library that you can use with JSP pages 
to make writing the JSP pages easier. 

Other view creation possibilities may better fit your needs. The following sec- 
tions explain a sampling of your options. 



• •••••• 



••••••••• 



Template engines 



Template engines are characterized by a separation of the page design from 
page data. This methodology offers several advantages over plain vanilla JSP, 
such as 
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More flexibility in site design 
Easier design development for graphics people 

ter control of the consistency of the site appearance 



In the following sections, we discuss three template engines. 
Apache Cocoon and the Cocoon plug-in 

The Apache Cocoon project is a Web application framework built on the 
premise of separating concerns, that is, separating presentation from logic 
from data. Apache Cocoon contains pipelines (a particular path for the flow 
of transformations) that create XML data from various sources and then trans- 
form that data into various presentation technologies through the use of XSL 
(extensible Stylesheet Language) stylesheets. Cocoon offers a wide range of 
possible transformations, including JSP, Velocity, FreeMarker, PHP, and XSP. 
For more information see cocoon.apache.org. 

The Cocoon plug-in allows Struts to pass forwards to Cocoon for transforma- 
tion in one of Cocoon's pipelines. (A forward, more exactly known as an 
Acti on Forward, is a mechanism that defines the passing of control to another 
resource, usually a JSP page or a servlet.) See struts . sourcef orge . net/ 
struts - cocoon/ index, html for more information. 



Jakarta Velocity and VelocityStruts 

Velocity is a Jakarta project — a Java-based template engine that provides a 
simple scripting language to create pages. No Java code is allowed in the pages. 
For further information on Jakarta Velocity, see Jakarta. apache. org/ 
vel oci ty . html . 

VelocityStruts is an extension to Struts that seamlessly marries the Struts 
Framework to Velocity. With the VelocityStruts extension, developers can for- 
ward a request to a Velocity template instead of to a JSP page. The nice thing 
about this method is that you are not forced to choose between one technol- 
ogy or the other. You can mix and match as you see fit. To find out more about 
VelocityStruts, see j a karta. apache, org/velocity /tools /struts/. 



FreeMarker 

FreeMarker generates text output (anything from HTML to PDF files) based 
on templates. The FreeMarker templates are essentially page designs that 
contain no application logic, only page design information. This provides a 
clean separation of concerns between page designers and application pro- 
grammers. The framework works with Struts out-of-the-box and replaces the 
use of JSP and JSP tag libraries as presentation technologies. 



FreeMarker is an open source project. Further information on FreeMarker can 
be found atfreemarker.sourceforge.net. 
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ntage of an XML document is that you can use XSL stylesheets to 
the document into virtually any other type of document for presen- 
tation. This transformation process is advantageous for sites that need to 
offer many forms of display to the user. For example, you may want to let the 
user view a purchase order in HTML, PDF, or plain text. This section describes 
two tools that integrate with Struts to provide XML and XSL services. 



StrutsCX 

The StrutsCX framework replaces JSP with XSLT (extensible Stylesheet 
Language Transformations). StrutsCX outputs well-formed XML that can then 
be transformed into any number of presentation markup languages (HTML, 
CSV, PDF, WML, and so on) using XSL stylesheets. See i t . cappucci nonet . 
com/stmtscx/i ndex . php for more information on StrutsCX. 



stxx 

The four letters stxx are an acronym for Struts for Transforming XML with XSL. 
The stxx technology bills itself as an extension to the Struts framework that 
allows an action to return an XML document that will be transformed into the 
final presentation form by XSL or Velocity. The purpose of this system is to 
provide an alternative presentation technology to JSP. However, you can 
still use JSP alongside stxx. Take a look at stxx.sourceforge.net to find 
out more. 



Internationalization 

The world of today is much closer than the world of a decade ago, and the 
world of tomorrow will be even closer. This shrinking of boundaries is due in 
part to the instant communication now available to most citizens and organi- 
zations. Communication is further enhanced by the creation of virtual repre- 
sentations of people and organizations through the use of the World Wide Web. 



When you plan an application for the Web, you need to keep in mind the audi- 
ence for the application. If there is any chance that the application might be 
used by people from different locales, you should plan to design for that pos- 
sibility right from the start. 

I18N is a lazy (or smart) person's way of saying Internationalization: /, plus 18 
characters in between, plus N. Some clever person, whose typing was probably 
challenged like ours, decided to make a challenging word more acceptable. 
As they say, necessity is the mother of invention. 
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ating a Web application that supports multiple locales, you need to 
bTisTdW how to present information in the preferred language and custom- 
ary formatting style of your audience. Customary formatting style refers to 
locale-sensitive information such as dates, times, numbers, and currency. 

Struts displays I18N text and images through the use of message resources and 
specialized tag libraries. We touch briefly on these capabilities in Chapter 3 in 
the "The login.jsp page" section, where we describe the creation of JSP pages 
for our sample Login Web application. The JSTL tag libraries provide the means 
to format dates, times, and numbers in the locale-specific style. (We address 
formatting for locales separately in Chapter 10.) 

To create applications with multilanguage capabilities, you work with two 
aspects of Jakarta Struts: the resource bundle properties file and the tag 
libraries to reference the resource bundles. 



Creating the resource bundle properties file 

The resource bundle contains all the text that the application will display to 
the user. The file can have any name that you choose but should have an 
extension of .properties. The file may also contain image locations if you 
want to display different images for different locales. The text and images 
might be one or more of the following: 

f Labels on fields and buttons 

Titles of pages or sections and page content 
v 0 Messages to tell the user something 
f* Icons that indicate an action to be performed 

Any content that you need to localize must be in the resource bundle. 

Each entry of text or image location requires a key that identifies that text or 
image location. For example, the following illustrates a key and the key's 
associated value. 



def aul tdi sk=My Disk 



The defaultdisk key is used to look up the text value of My Disk. 

Sometimes it may be convenient to divide the key-value pairs into different 
files, especially if you have multiple developers or modules in your application. 
The only requirement is that you set them up properly in the struts config 
file, as we explain in the next section. 
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Configuring the message resources 

Tc|tell Struts about your message resources (or resource bundles), you need 

a <message-resources> tag in the struts-conf i g file and specify 
xtinthe web.xml file. In the struts-conf i g file, the <message- 
resources> tag has five possible attributes: 



cl assName: Optional. The fully qualified name of the configuration 
class. This value defaults to org. apache, struts, config. Message 
ResourcesConf i g. Use this attribute only if you subclass Message 
ResourcesConf i g. 

is* factory: Optional. The fully qualified name of MessageResources 
Factory. This value defaults to org .apache . struts . uti 1 . Property 
Message Re sourcesFactory. Use this attribute only if you subclass 

Property Message Re sourcesFactory. 

key: Optional. The attribute key to store this bundle in the Servlet con- 
text. The key defaults to org . apache .struts . acti on .MESSAGE. If you 
use multiple resource bundles in your application, you should set a dif- 
ferent key for each one. In the application, you would use the key to indi- 
cate which bundle to select. 

nul 1 : Optional. Determines how to display missing resources. The 
default value is true and displays missing resources as nul 1 . If you set 
the value to f a 1 s e , the missing resource is displayed as lllkeylll. 
This option is useful during development because it helps you to spot 
missing resources. 

parameter: Required. The name of the resource bundle. This is the 
name of the message resource file, minus the . properti es extension. 

Here is an example of a message -resources tag in the struts config file: 

<!-- ========== Message Resources Definition ================== --> 

<mes sage -resources nul l="fal se" parameter="Appl i cati onResources"/) 

This tag specifies the name of the resource bundle as Appli cati onResources. 
Because the null parameter is set to fa 1 se, if the referenced resource is 
missing, you see a display like this: 1 llkeyl 1 1 . 

If you have two resource bundles, you need to also define a key for each to 
reference them properly in your application. Here is an example of configur- 
ing the message resources for two resource bundles: 

<!-- ========== Message Resources Definitions ================== --> 

<mes sage -resources key="purchasi ng" pa r ame t e r= " Pu r cha s i ng Resources"/) 
<message-resources key=" vendors" parameter="VendorResources"/> 
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In this example, a key is associated with each resource bundle. When you 
need to reference one of the bundles, you must specify the bundle's key as 
example, using the JSTL tag <fmt :message>. We show examples of 
: message) tag in the next section. 



The web . xml file also needs to be set up to know about the resource bundles. 
Otherwise you're required to specify the resource bundles in the JSP page 
using special JSTL tags. To set up the web . xml file, add the following snippet 
to the beginning of the file: 



<web-app> 






1 <context-param> 

2 <param-name> 

3 javax.servlet.jsp.jstl 
</param-name> 


. fmt . 1 ocal i zati onC 


ontext 


4 <param-val ue> 

5 Appl i cati onResources 
</param-val ue> 

</context-param> 






</web-app> 







You can specify only the default resource bundle in the web . xml file. If you 
use more than one resource bundle, you must specify the nondefault bundle 
name in the JSTL tags. 

In the preceding code, note the following: 



Line 1: Adds a context parameter tag. The context represents the scope 
called appl i cati on. All key-value pairs stored in the context are avail- 
able everywhere in the application. 

Line 2: Adds the parameter name tag for the context. 

i>* Line 3: Specifies the complete class name of the context parameter. In 
this case, we're defining the context parameter to be the class that rep- 
resents FMT_LOCALIZATION_CONTEXT used by the JSTL tag library. 

JSTL has numerous configuration items that contain the default values 
for such settings as locale, resource bundle, time zone, and SQL data- 
source. The FMT_LOCALIZATION_CONTEXT contains the default resource 
bundle and its associated locale. This resource bundle will be used for 
all message lookups unless an alternate is specified in the JSP page. See 
Chapter 10 for more information on JSTL. 

V Line 4: Adds the parameter value tag for the context. 

Line 5: Specifies the name of the resource bundle to be included in 

FMT_L0CALIZATI0N_C0NTEXT. In this case, the name is Appl i cati on 
Resources. 
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The position of tags in the web . xml file is important. For example, the 
<context-param> tag must come before the <servl et> tag. 

e tag library to display messages 

When you've defined and configured your message resources, the next step is 
to integrate them into your JSP pages. Both the Struts-EL and JSTL tag libraries 
provide such functionality The Struts-EL library has a tag designed for I18N 
called the <bean : message) tag. However, because the JSTL tag library also has 
tags to use for I18N — <fmt : message) and <f mt : parameter) — we'll use 
them. The creators of Struts have recommended using JSTL whenever possible. 



Whenever you want to display text in your JSP page, rather than putting the 
text statically in an HTML tag such as <Ti tl e>Thi s is the Title Page 
</Ti tl e>, you can instead use the <fmt : message) tag and retrieve the text 
from the resource bundle. For example, suppose that you have defined the 
title of the page in a resource bundle by using a key of homepage .title: 



homepage . ti tl e=Thi s is the Title Page 



The <fmt :message> tag would look like this: 



<fmt:message key 


= " homepage 


.title" /: 


> 








And your HTML would now look 1 


ike this: 







<ti tl eXfmt : message key=" homepage . ti tl e" /></title> 



If you have more than one resource bundle defined in struts-config, you 
need to specify another tag when you want to reference the non-default 
resource bundle. The <fmt : setBundl e> or <fmt : bundl e> tag needs to spec- 
ify the name of the resource bundle subsequent <fmt : message) tags will ref- 
erence. See Chapter 10 for more information on these tags. 



Creating parameterized messages 

Besides defining plain text messages in the message resource file, you can 
also create parameterized messages. This is a great feature if you need to 
insert specific information into a message at runtime. Struts supports mes- 
sages with up to four parameters ({ 0 ) through { 3 ) ) . In Chapter 3, we 
develop a message resource file containing an example of a parameterized 
message. Here is the parameterized message from that example: 

1 oggedi n .msg=Wel come , {0). You are now logged in. 

This message's placeholder, { 0 ) , indicates that the first parameter that gets 
passed should replace the { 0 ) . When you specify the use of the message in 
the JSP page, the tag looks like this: 
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<fmt : mess age key="l oggedin.msg"> 

<fmt:param val ue= ' $ { requestScope . userName ) ' /> 
,message> 




The parameter that is being passed is the user's name, which will replace the 
{ 0 ) when the message is output to the page. 

Setting up message resource files for different locates 

The final step when preparing your application for I18N is to create additional 
resource bundles for each locale that you intend to support. Each locale needs 
a two-character language specifier. In addition, you may choose to further 
refine the locale with a two-character country code. For example, f r refers 
to the French language in general and f r_CA references French as used in 
Canada and f r_FR is French as used in France. 

You don't need to add additional files to any configuration. Assuming that 
you have defined the default resource bundle name in the struts config 
file, you append the locale specifier to the default resource name to find any 
locale-specific bundle. For example, if Appli cat ion Re sources is the default 
resource bundle name, Appl i cati onResources_f r is the name used for the 
French language version of the resource bundle. 

Here are the full definitions of the two bundles. Lines starting with a number 
sign (#) are comments. 

The following is from the Appl i cati onResources.properti es file: 

# default locale messages 
greeti ngs = Hel 1 o . 

f arewel 1 =Goodbye . 
inquiry=How are you? 

The following is from the Appl i cati onResources_f r . properti es file: 

# French locale messages 
greeti ngs=Bon jour. 
farewell=Au revoir. 

i nqui ry=Comment allez-vous? 

For a list of all language codes, see 

f tp . i cs . uci . edu/pub/ i etf /http/rel ated/i so 639 . txt 

For a list of all two-digit country codes, see 

userpage.chemie.fu-berlin.de/di verse /doc/ 1 S0_3 166 .html 

You can also reference resource bundles in your server-side Java code. We 
show section examples in the "Mediating between the View and the Controller" 
section, later in this chapter. 
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An 118n example 

Ttje Login application you create in Chapter 3 is an ideal candidate for inter- 
relation. Everything is set up to take advantage of I18N; all that you 
k fc<lo is to create a new message resource file. To see I18N in action, 
simply make a copy of the Appli cat ion Re sources, p rope rties file and 
name it Appl i cati onResources_de . properti es to create a message 
resource file for German. Then edit the Appl i cati on Re sources _de. 
properties file to look like Listing 6-1. 




Listing 6-1 The German Version of the ApplicationResources File 

# Resources for Login Project 

# Struts Validator Error Messages 

# These are special resources that the Struts tag library 

# uses to format messages. In this case we make sure that 

# errors are red so that they can be noticed, 
errors. header=<font color="red">* 

errors. footer=</font> 

terrors 

error.username.required=Benutzername notwendig. 
error.password.required=Passwort notwendig. 

error . 1 ogi n . i nval i d=Das System konnte Ihren Benutzernamen und 
Passwort nicht bestintigen. Haben Sie die Feststell- 
Taste an? Bitte versuchen Sie es nochmal . 

#1 ogi n page 

1 ogi n . ti tl e=Anmel dungsprojekt - Bitte, anmelden 

1 ogi n .message=Bi tte anmelden 

login. username=Benutzername : 

login. password=Passwort : 

1 ogi n . button . si gnon=Anmel dung 

#loggedin page 

loggedin.title=Anmeldungsprojekt 

1 oggedi n .msg=Wi 1 1 kommen , {0). Sie sind jetzt angemeldet. 

Copy the Appli cati on Re sources _de. properties file into the WEB - 1 NF/ 
classes folder of the Login application in the Tomcat webapps folder. Then 
restart Tomcat. 

In your Web browser, you must set the default language to German. When you 
do so, the browser tells the Web server the user's preferred language. 

Setting the language preference in Internet Explorer 

To set the default language in Internet Explorer 6.0, follow these steps: 

1. Choose ToolsOInternet Options. 

The Internet Options dialog box appears. 
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2. Click the General tab. 

the bottom of the General tab, click the Languages button. 

Language Preference dialog box appears. 
4. Click the Add button. 

The Add Language dialog box appears, as shown in Figure 6-1. 



Figure 6-1: 

Internet 
Explorer's 
Add 
Language 
dialog box. 



Acid Language 



LQ 



Language: 

FYRO Macedonian [mk] 
Gaelic [gd] 
Galtian [gl] 
Georgian [ka] 
German (Austria) [de-at] 
German (Germany) [de] 
Geirndf (Liechi.ei i.vn/ [de-lij 
German (Luxembourg) [de-lu] 
German (Switzerland) [de-ch] 
Greek [el] 
Gujarati [gu] 
Hebrew [he] 
Hindi [hi] 
Hungarian [hu] 



□ 



[v] 



OK | Cancel 



5. Scroll down to find the language you want to set as a default. 

To follow along with the example, look for an entry for German. There 
should be several, one for each country that speaks German. Because 
the resource bundle in this example is for German in general and not for 
a particular country, you can choose any German option. 

6. Select the language option you want, and then click OK. 

You are returned to the Language Preference dialog box, as shown in 
Figure 6-2. 

7. Select the new German entry and click the Move Up button until the 
German entry is at the top. 



Figure 6-2: 

Internet 
Explorer's 
Language 
Preference 
dialog box. 



1 annnano PrufcrsnrD 


me=a 


Some Web sites offer content in multiple languages. You can 


choose several languages below; they will be treated in order of 


priority. 




Language: 






German (Germany) [de] 


[ Move Up ] 




English (United States) [en-us] 








| Move Down 






| Remove | 






Add... | 


Menus and dialog boxes are currently displayed 




in English (United States), 






OK 


| Cancel | 
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^jttNG-' When this test is over, be sure to delete the German entry unless you want 

to see your Web sites in German from now on. Re-open the Language 
^ ^\ lyP|«^erence dialog box, choose the German entry, and click the Remove 

JWfKmJ \J Iv^Jon. Click OK to close the dialog box. 

8. Click OK twice to close both open dialog boxes. 

Internet Explorer is ready to go. Other versions of Internet Explorer use a 
similar mechanism to set the language preference. 

Setting the language preference in Netscape Navigator 

To set the language default in Netscape 7.0, follow these steps: 

1. Choose EditoPreferences. 

The Preferences dialog box appears. 

2. In the Category pane, click the arrow next to Navigator. 

3. Click the Languages option. 

The Languages Panel appears on the right, as shown in Figure 6-3. 



Figure 6-3: 

Netscape 
Navigator's 
Preferences 
dialog box 
with the 
Languages 
option 
selected. 



C ategorj 
!> Appearance 
^Navigator 
Histi 



Helper Applications 
Smart Browsing 
Internet Search 
Tabbed Browsing 
Downloads 

E> Composer 

t> Mail & Newsgroups 

E> Instant Messenger 

l> ICQ 

E> Privacy & Security 
> Advanced 
Offline & Disk Space 



Languages 



Languages for Web Pages 

Web pages are sometimes available in more than one language 
languages for displaying web pages, in order of preference. 
Languages in order of preference: 



English/United Stale-: 



Character Coding 










Default Character Coding: | Western (IS 0-88 


59-1) 





OK ) l.incel Help 



4. Click the Add button. 

The Add Language dialog box appears. 

5. Scroll down to find and select the language that you want. 
To follow along with the example, choose any German item. 

6. Click OK to close the dialog box. 
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In the Languages pane of the Preferences dialog box, select the 
German entry and then click the Move Up button until the German 
y is at the top. 



OK to close the Preferences dialog box. 



Netscape is ready to go. Other versions of Netscape Navigator set the lan- 
guage preference in a similar fashion. 



Testing the internationalized application 

In your browser, type the URL for the Login page (http : / /I ocal host/ 
Logi n). The initial page should now be displayed in German, as shown in 
Figure 6-4. 



Figure 6-4: 

The Login 
page 
displayed in 
German. 



Anmeldungsprojekt - Bitte, anmelden - Microsoft Internet Explorer 0®S 
File Edit View Favorites Tools Help 


©Back - © • g| fj ps^h 


Favorites ^ ' Media 


Addieiv: .jfl http://localhost(login/login.jsp jv] Go Links " OBSnatft L# 


^■Search - | Google • 


AltaVista " Ask Jeeves More • 


Bitte anmelden 


Benutzemame: [ 




1 


Passwort: 




1 


| Anmeldung | 












£] Done 




* J Local intranet 



Enter a valid user name and password, and then log in. The normal logged-in 
message should now be displayed in German. Neat! 



Using one source for String type constants 

You may not think your application really needs I18N if only people in your 
company will see it. Nevertheless, you should consider using the I18N mecha- 
nism described in the previous sections for another reason — consolidating 
textual content for ease of maintenance. Often, especially for larger applica- 
tions, the same textual content is displayed in many places throughout the 
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application. During the lifetime of the application, you may need to change 
the text to meet some unforeseen need or demand of the marketplace. 



pie, each page may have a button with the label OK. After the appli- 
cation has been in production for a while, usability experts may conclude 
that OK is confusing for some people and a better button label would be 
Save. To make that change, you would have to search all pages for instances 
of OK buttons and change the labels to Save. You might easily miss one or 
more instances. 

If all the displayed text comes from message resources, however, you can 
easily find the reference to the OK button in the message resources and make 
one change there. This change will propagate throughout the application 
automatically when you restart the application. The maintenance is easy and 
there's no chance of missing an occurrence. Do less and accomplish more! 



Mediating between the VieuJ and 
the Controller 

When users fill out a form on a Web page, you need to collect that data for 
processing in the Act i on subclass that will handle the request. You create 
the movement of form data from the View to the Controller by using a form- 
bean. Here we discuss the role of formbeans in detail. 

A formbean is an extension of the Act ion Form abstract class. The purpose of 
the formbean is to provide a consistent container to store the View's form 
data for presentation to the Controller. That being the case, the formbean 
requires little content — just the View's properties and their associated 
getter and setter methods. And that's the way it should be. The formbean 
shouldn't contain business logic or any other specific methods. The form- 
bean is a data transfer mechanism — that's all. 

When defining the properties of the formbean, you need to take into account 
that the form properties in the View are always Stri ng types. Even if the con- 
tent displayed is a numerical value, such as 129.09, the content is always a 
string. The data may not be stored as a string in the backend database, but 
it's always displayed using strings in an HTML form. As a result, you may 
need to perform the following: 

i>* When a form is submitted, convert the string into its numeric format 
after it's taken out of the formbean. 

i>* Before a View is presented, convert the data from a numeric value to a 
string before populating the formbean. 
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We've found one exception when using the Struts tag library. The Struts tag 
for displaying an HTML check box assumes that the underlying value in the 
a boolean primitive type. However, when the HTML form is sub- 
displayed, the check box uses a string value to determine whether 
the check box was or should be checked. The bottom line is that when using 
ungrouped check boxes on a form, the formbean property type should be 
boolean, not String. 
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Configuring the formbean 

Listing 6-2 contains the configuration file for the example Login application. 
For more information on this application, see Chapter 3, where we discuss 
how to configure f ormbeans in the struts config file. In this section, we 
explain the file from the angle of how it mediates between the View and the 
Controller. 



Listing 6-2 struts-config.xml 

K?xml version="1.0" encodi ng=" ISO-8859-1" ?> 
Z< ! DOCTYPE struts-config PUBLIC 

3 "-//Apache Software Foundati on//DTD Struts Configuration 1.1//EN" 

4 "http: //Jakarta .apache.org/struts/dtds/struts-confi g_l 1 . d t d " > 



5<!-- This is the Struts configuration file for Login example application --> 
6<struts-conf i g> 

7 <!-- ========== FormBean Definitions ================================= --> 

8 <form-beans> 

9 <form-bean name="loginForm" 

10 type="dummi es .struts . Logi nForm"/> 

11 </form-beans> 



12 <!-- ========== Action Mapping Definitions ========================== --> 

13 <acti on-mappi ngs> 

14 <action path="/login" 

15 type="dummi es .struts . Logi nActi on" 

16 name="loginForm" 

17 scope="request" 

18 input="/login.jsp" 

19 val idate="true"> 

20 <forward name="fai 1 ure" path="/login.jsp"/> 

21 <forward name="success" path="/l oggedi n .jsp"/> 

22 </action> 

23 </action-mappings> 



24 <!-- ========== Message Resources Definitions ====================== --> 

25 <message-resources null="false" 

26 parameter="Appl i cati onResources"/) 
27</struts-config> 
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9: Uses the <form-bean> tag to give Logi nForm a name that you can 
to later in the struts conf i g file. You must define every FormBean 
you intend to use in an application, using the <form-bean> tag. The 
Login application has only one FormBean, Logi nForm. 

V Line 10: Specifies the full class name of the form and closes the tag. Lines 
9 and 10 tell the Controller how to create the formbean at runtime. 

Line 16: Specifies which formbean should be associated with this action. 
In this case, the code uses the 1 ogi nf orm defined in line 9. 

Line 17: Specifies that the scope of the formbean should be the request 
scope. In other words, where should the formbean exist? The default 
scope is request, so this line is not really required. The other possibil- 
ity is the s e s s i o n scope. 

V* Line 18: Specifies that the 1 ogi n . j sp page populates the formbean. 

Line 19: Specifies that the val i date method of the formbean should be 
called. Fal se would mean not to call the va 1 i date method, and valida- 
tion would need to occur through some another means. (For more infor- 
mation about other means of validation, see the "Validating the Data" 
section later in this chapter). 



Interactions u/ith the formbean 

The steps of the Controller's interaction with the formbean are presented in 
Chapter 4 in the "Working with the Controller's Helper-RequestProcessor" 
section. Here is a summary of the pertinent steps RequestProcessor takes 
when handling Acti onForm: 

1. Gets the Acti onForm associated with the request. 

RequestProcessor gets the Acti on Form associated with this 
action based onActionMapping.IfActionForm doesn't exist, 
RequestProcessor creates it. RequestProcessor then calls the 
reset method of Acti on Form. 

2. Populates Acti onForm. 

The Acti onForm is populated with the parameters received from the 
request. 

3. Validates Acti onForm. 

If you're using standard form validation (val i date=" true"), 
RequestProcessor calls the ActionForm's validate method now. 
If the validation has any errors, RequestProcessor forwards control 
back to the page from which the request came. 

4. Calls the execute method on the specific Acti on class. 
Finally, the Acti on class gets to do its stuff. 
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Preparing the form u/ith the reset method 



dard reset method does nothing by default. This is appropriate 
the reset method would know nothing about the properties of your 
formbean. You have the responsibility to write the appropriate code to set all 
your form properties back to their default state. 

Why is resetting property values necessary? Actually you don't need to reset 
values if your formbean is stored in the request scope because the formbean 
gets reinstantiated for each new request anyway. However, if you elect to 
store the formbean in the session scope, you need to make sure that the 
values from the previous use are cleared before using the formbean again 
because each new request uses the same copy of the formbean. 

Resetting property values generally consists of setting the values back to 



null, or the empty string. Here is an example 1 


:rom our Login application: 


public void reset(Acti onMappi ng mappir 
HttpServl etRequest r 


g. 

equest ) 





password 
userName 



Indexing data 

If you need to display multiple rows of the same type of data, you may also 
need to define indexed properties in your formbean. An example would be the 
display of rows of purchase-order line-item information. You can define indexed 
properties by using standard Java arrays, Collections, or Maps. You use the 
various tag libraries to reference this data, which we discuss in Chapter 10. 

A Collection is an interface and the root definition of a set of classes that hold 
groups of data objects. A. Map is also an interface and root definition of a 
group of classes that hold data as keys mapped to values. The implementa- 
tions of Collection and Map vary depending on how the objects or key values 
are stored. Developers choose a particular implementation of a Collection or 
Map based on the needs of the application. For example, you need to con- 
sider whether the data needs to be sorted or unsorted, whether or not the 
access needs to be thread safe, and whether or not duplicate values are 
allowed. See the Java SDK API documentation for details. 




Validating data 

Frequently, JSP pages have forms for the user to complete. The required 
information could be as simple as a user name and password, or you could 
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have a complex order-entry form. You often want to make sure that the data 
the user entered is valid before trying to process the data. For example, if the 
rs a date, you should verify that the date meets all the criteria of a 
before passing the value to a database. The data may not be in the 
proper format for a date. Or the date might be in the proper format but too 
far in the future or past to be acceptable. 



The standard mechanism for validating form data is to override the validate 
method intheActionForm class and to enter there all the logic necessary to 
determine whether or not the form data is acceptable. RequestProcessor 
calls this method immediately before calling the execute method in the 
Acti on instance. 



Listing 6-3 shows an example of overriding the validate method. 



Listing 6-3 Overridden Validate Method from a Login formbean 

1 public ActionErrors val idate(ActionMapping mapping, 

HttpServletRequest request) 

2 I 

// create an empty ActionErrors instance 

3 ActionErrors errors = new ActionErrorst ) ; 



// test for presence of user name 

4 if((userName == null) || (userName . 1 ength ( ) < 1)) 

5 errors . add ( "userName" , new ActionErrorC'error.username. required")); 
// test for presence of password 

6 if((password == null) || (password. 1 ength ( ) < 1)) 

7 errors . add ( "password" , new Acti onError( "error . password . requi red" )) ; 
// test for proper password length 

8 else if ((password. length < 5) | (password. length > 8)) 

9 errors . add ( "password" , new Acti onError( "error .password. 1 ength" )) ; 



// return the ActionErrors object 

10 return errors; 

11 } 



In Listing 6-3, note the following: 



Line 3: Creates an empty ActionErrors object, which is the return 
value for the method. 

v 0 Lines 4 and 6: Test to ensure that the user actually enters something for 

the userName and password fields. 

Line 8: Tests to make sure that the password is a proper length (5 to 8 
characters). 

If any test fails, the code creates an Acti on Error object and adds it to the 
ActionErrors instance. When creating the ActionError instance, a mes- 
sage resource key is passed to indicate which message should be displayed. 
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Note that when adding Acti onError to Acti onErrors, the code specifies a 
particular key (either username or password) so that the JSP page will know 
splay the error. 



Declarative form Validation 

Another way to perform validation is to use the declarative mechanism found 
in the Validator plug-in. The Validator plug-in is discussed in Chapter 9. 



Notifying Users of Problems 



Whether validating a form or testing logical operations, you need a common 
way to notify the user of the problem when an error arises. Acti onError and 
Acti onErrors are Struts classes created for that purpose. 

Acti onError is a subclass of Acti onMessage that holds an error message 
that will be returned to the user. You specify the message by using a key of a 
message resource. If the message is parameterized, you can add the values for 
the parameters to Acti onError. Amessage can have up to four parameters. 

Here are examples of Acti onError constructors using the message resource 
file in Listing 6-2: 

// constructor with just the message's key 
ActionError ae = Acti onError( "error . username . requi red" ) ; 
// constructor with key and one parameter 
ActionError ae = 

Act ionError(" error. username. requi red" , "Mi ke" ) ; 

Acti onErrors is a subclass ofActionMessages and is a wrapper class 
used to hold one or more instances of Acti onError. Two constructors are 
possible — one creating an empty Acti onErrors and the other creating an 
Acti onErrors with the same messages as those in another instance of 
Acti onErrors. Here are examples of the two constructors: 

// empty constructor 

ActionErrors aes = new ActionErrors( ) ; 

// constructor taking an ActionErrors instance 

ActionErrors aes2 = new Acti onErrors ( aes ) ; 

When you need to add an Acti onError to the Acti onErrors instance, use 
the add method. Its signature is 



public void add(String property, ActionError error) 
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where property refers to the form entry that the error is indicating. For gen- 
eral errors that apply to the entire form, use Acti onErrors . GL0BAL_ERR0R. 

ror specific to a particular field, use the property value of the field. 




our example application, Login, we tied specific errors to the userName 
and password properties in the va 1 i date method of the Logi nForm class. 

// create ActionErrors instance 

ActionErrors errors = new Acti onErrors () ; 

i f( ( userName == null) | ( userName . 1 ength ( ) < 1)) 

// if a username error, create ActionError 

// and tie it to UserName 

errors . add( " userName" , new 

Act ionError(" error. userna me. requi red")); 
if((password == null) | ( password . 1 ength ( ) < 1)) 

// if a password error, create ActionError 

// and tie it to password 

errors . add( " password" , new 

Act ionError(" error. password. requi red")); 
return errors; 

In the 1 o g i n . j s p page of the Login application, we took advantage of the 
error property value to display the particular error next to the appropriate 
field. Here are two segments from that page. Notice the correspondence 
between the property of the html : text tag, the property of the html : errors 
tag, and the property used in the preceding errors, add methods. 

<html :text property="userName" 
size="15" 
maxlength="15" /> 
<html:errors property="userName" /> 
<html :password property="password" 
size="15" 
maxl ength=" 15" 
redi spl ay = "f al se" /> 
<html :errors property="password" /> 

Acti onMessages and Acti onMessage can be used just like Acti onErrors and 
Acti on Error. However, in the JSP file, the <html : messages) tag should be 
used instead of <html : errors). In general, Acti onMessages are informative 
messages to the user and ActionErrorisan error message. For example, you 
may want to inform the user when a requested operation gets performed suc- 
cessfully, such as when a record gets inserted into the database without error. 



Mediating Automatically 



Although ActionForms are useful for conveying request information to the 
Controller from the presentation page, they're sometimes a hassle if the form 
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contains only simple data that you want to gather. Struts has a slick mechanism 
to dynamically create the necessary formbean without the developer having 
the Acti on Form class. This mechanism can be used by creating 
s in the struts config file. The principal Struts class that you use 
is called the DynaActi on Form. 



Configuring the DynaActionForm class 

Configuring a DynaActi on Form is not much different from configuring a regular 
Acti onForm. The definition still goes in a <form bean> tag in the struts- 
conf i g file. However, rather than specifying your extended Acti on Form class 
for the type attribute, you use the full class name of the DynaActi on Form 
class. In addition, you specify the form properties that will be implemented by 
the formbean. Listing 6-4 is an example of how to implement Log i n Form (from 
the Login example application in Chapter 3) as a DynaActi on Form instead of 
an Acti on form. 



Listing 6-4 Configuring DynaActionForm 

1 <form-bean name="l oginForm" 



2 type=" org. apache .struts. acti on. DynaActi on Form") 

3 <form-property name="userName" 

4 type=" Java . 1 ang . String" 

5 i n i t i a 1 = " " / > 

6 <form-property name="password" 

7 type="java.lang. String" 

8 initial=""/> 



9 </form-bean) 



Listing 6-4 has the following noteworthy items: 

W Line 2: Declares the class to instantiate to be the DynaActionForm class. 

Lines 3-5: Define one property named user Name of type String whose 
initial value is the empty string. 

Lines 6-8: Define another property password, also of type String and 
with an initial value of the empty string. 

As you can see, the configuration of a DynaActi on Form and an Acti on Form 
are similar. Note that when you are using DynaActi on Fo rm, you must make 
some changes to the Acti on class when referencing DynaActi on Form values. 
These changes are described in the next section. 
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Differences beWeen ActionForm 
D TO P B 0 Qffi$y n *ActionForni 

Although ActionForm and DynaActionForm are similar, you do need to take 
into account a few differences. The following differences stand out: 

t<" The DynaAct ion Form doesn't have reset or vali date methods avail- 
able. (They exist but they're both empty methods.) Intuitively it makes 
sense that r e s e t is not present; DynaActionForms are generated with 
each request, so there's no need to reset values. 

If you want a DynaActi on Form and you also need to call a reset or 
val i date method, you must subclass DynaActi on Form and override 
the reset or vali date method. But if you go to that much trouble, you 
might as well stick with the Act ion Form class. 

The alternative to subclassing the DynaActi onForm to perform valida- 
tion is to use the Val i d a t o r plug-in. We discuss this mechanism in 
Chapter 9. 

i>* The formbean properties are referenced differently in the Acti on class. 
DynaActi onForm properties are no longer simple scalar values that can 
be referenced with getter and setter methods. Using these methods 
will not work because the formbean is created dynamically by reading 
the formbean configuration properties. Consequently, the form's proper- 
ties are put into a Map structure and referenced by the property name. 
This means that in the Acti on class, rather than referencing the user- 
name value like this: 

String user = ( ( Logi nForm) f orm) . getUserName ( ) ; 
You must now use the Map syntax of providing a key to do the lookup: 

String user = 

(String)((DynaActionForm)form).get("userName"); 

\S You reference a form property in a JSP page differently. Assuming that 
you're using the Struts-EL or JSTL tag library, you reference a property 
of a standard formbean using the expression language (EL) syntax, like 
this: 

${form bean. property) 

But because a DynaActi on formbean has all the properties stored in a 
Map structure, you must reference them by using a slightly different 
syntax, such as 

${dynabean. map. property) 
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Chapter 7 

the Configuration 



In This Chapter 

Using configuration files 
Developing the Web container configuration 
Showing an example of Web container configuration 
Developing the Struts framework configuration 
Showing an example of a Struts configuration 



tMyhen you've finished creating the Model, View, and Controller sections 
WW of your Web application, you need to tie all the parts together. Like a 
kid who puts on his shoes without taking the time to tie his shoelaces — he 
quickly falls on his face — your Web application won't go anywhere without 
the configuration files. We describe many configuration examples throughout 
the previous six chapters. In this chapter, we bring it all together and cover 
all aspects of configuring Struts. 
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Stringing the Parts Together 

The Struts framework offers a lot of flexibility for developers putting together 
Web applications. The configuration files are instrumental in implementing 
much of that flexibility by enabling you to 

Fine-tune the functioning of the various components of the framework 
v 0 Specify the developer components that you're adding 
u* Define how to treat the added components 
V Specify what happens in case of errors 
i>* Include I18N information 

Extend the framework 
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When you set up your Struts application, you need to consider two configura- 
tion files: web . xml and struts -conf i g . xml . The web . xml file defines the 
your Struts application that the Web container needs to know about, 
ts-config.xml informs the Struts framework about the pieces of the 
Struts application that you've added to the framework. 



Editing the Web Container 
Configuration File 

The Web container reads the web . xml file to discover specific information 
about the application, in particular what kind of resources it contains. You 
can find the definition of the specification we're using for web . xml in the Java 
Servlet Specification version 2.3. You can download this specification from 
Sun's Web site at 

Java. sun. com/products/servlet/download. html 

This section is not a complete description of the web . xml specification. Instead, 
we cover only the parts of the specification that directly relate to Struts. 

A Document Type Definition (DTD) file defines the XML grammar used in an 
XML document. The web . xml file has a particular DTD associated with it. 
That DTD is too long to be included in this book. To see the entire DTD, look 
at the Java Servlet Specification version 2.3 mentioned previously or go to 
Java . sun . com/dtd/web-app_2_3 . dtd. However, we describe some of the 
DTD to help explain the basic structure of a web . xml file. 



Reading a DTD: An overview 



The DTD provides a concise definition of the 
rules for specifying a particular type of XML 
document. The rules are extensive. Here we 
define the minimal set of rules that you need to 
know to make sense of the DTD grammar dis- 
cussed in this chapter. What are commonly 
referred to as tags in an XML document are 
known as elements in the XML grammar. You 
define elements through the following syntax: 

<!ELEMENT element-name ...> 

where . . . could be a text value or other 
elements. 



The simplestformfor an element definition is an 
element that's defined to have only a textual 
value, as shown here: 

<! ELEMENT element-name #PCDATA> 

The #PCDATA marker refers to parsed charac- 
ter data, but essentially means plain text. If an 
element contains one other element, describe it 
in parentheses, like this: 

<!ELEMENT element-name (other- 
el ement-name)> 



Chapter 7: Setting the Configuration 



It may be that the defined element can contain 
eipmts. For example, following 
Fff\(^^inina three other elements: 

<!ELEMENT element-name (other- 
el ement-namel , other- 
el ement-name2 , other- 
el ement-name3)> 

The elements contained in the element you're 
defining can be optional, mandatory, or appear 
multipletimes. To specify those qualities, follow 
these rules: 

If an element is optional but can occur only 
once, follow it with a ? 

*<" If an element is mandatory and can occur 
one or more times, follow it with a + 

*<" If an element is optional but can occur mul- 
tiple times, follow it with a * 

If an element appears without any of the 
previous markers, it is considered manda- 
tory but can appear only once 

When an element is defined to contain other 
elements, the sequence of the appearance of 
each element in the DTD must be the same as 
in the definition. 

Elements can have attribute 'sthat are a further 
qualification of the element. You define an 
attribute with the following syntax: 

<!ATTLIST element-name 

attribute-name attribute- 
type default-declaration) 



The el ement-name is the element name that 
you defined in the < ! ELEMENT definition. The 
attribute-name is the name that refers to the 
attribute. The attribute-type refers to 
what type of value that you can present for the 
attribute. Finally, default-declaration 
determines whether or not the attribute is 
required. 

The attri bute-type can be one of several 
values. For example, if the attri bute-type 
is C DATA, the attribute can take any text value. 
Another possibility is an entity (a shortcut to a 
commonly used value) that you define else- 
where in the DTD. To define the entity, use the 
following syntax: 



< ! ENTITY % ent-name 
stri ng"> 



' val ue- 



An example of an entity definition is 

<! ENTITY % ClassName "CDATA"> 

The entity is referenced as%ClassName;.An 
example of an attribute definition that uses an 
entity is the following: 

<!ATTLIST form-bean name 

%BeanName; #REQUI RED> 

You can enforce attributes also through the use 
of an optional default-declaration value. For 
example, you can place ^REQUIRED or 
//IMPLIED at the end of the definition. 
^REQUIRED means that the attribute must be 
defined forthe element; # I M P L I ED means the 
attribute is optional. 



All valid web . xml files must contain the following DOCTYPE declaration, indi- 
cating the version of the DTD to use: 

<!D0CTYPE web-app PUBLIC "-//Sun Microsystems, Inc. //DTD Web 
Application 2.3//EN" "http://java.sun.com/dtd/ 
web-app_2_3.dtd"> 

The root tag of the web . xml file is <web app>. This tag is always the first tag 
that you place in the web . xml file. The following DTD segment defines how 
you use the tag and lists all the possible other tags in it: 



Part II: Starting from the Core 



< ! LLLML 
di stri b 

DBocte 

resourc 



<!ELEMENT web-app (icon?, display-name?, description?, 
Die?, context-param*, filter*, f i 1 ter-mappi nc 
er*, servlet*, servl et-mappi ng* , sessi on-conf i g? , 
3* ,wel come-f i 1 e-1 i st? , error-page*, taglib*, 
r~es~ource-env-ref*, resource-ref*, security-constraint*, 
1 ogi n-conf i g? , securi ty-rol e* , env-entry*, ejb-ref*, 
ejb-1 ocal -ref*)> 



For more information about the syntax of a DTD, see the sidebar, "Reading a 
DTD: An overview." We show a complete example of a web . xml file at the end 
of this section. 



The SertftetContext confirmation taq 

Each Web container provides an implementation of the Servl etContext inter- 
face for each Web application running in the Web container. Any servlet can ref- 
erence the Servl etContext object, which can store and reference objects by 
any servlet in the application. The Servl etContext has a lifetime as long as 
the application is running. Store in the Servl etContext any data elements 
that need to be available on a global basis for the life of the application. 

The tag for inserting values into the Servl etContext is <context -pa ram>. 
The DTD syntax for the tag is 

<!ELEMENT context-pa ram (param-name, param-value, 
descri pti on? )> 

< ! ELEMENT param-name (#PCDATA)> 
< ! ELEMENT param-value (#PCDATA)> 
< ! ELEMENT description (#PCDATA)> 

In the DTD syntax, you include the following items: 

<param name> defines the name that references the param-value 

<param- va 1 ue> is the value of the attribute 

**" < descri pti on> is an optional tag that provides descriptive text about 
the parent element 

The following shows an example of the tag's use: 

<context-param> 
<param-name> 

javax. servlet. jsp.jstl.fmt. local izationContext 
</param-name> 
<param-val ue> 

Appli cat ion Re sources 
</param- val ue> 
</context-param> 
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In the example, we place into the Servl etContext one parameter named 
ja vax . servl et . jsp . jstl . f mt . local izationContext with a value of 

,ti on Resources. When you use the JSTL tag library, you can define 
It resource bundle in the web . xml file with this technique. In this 
way, you do not have to reference the resource bundle in the JSP when you 
need to retrieve messages from the resource bundle. (For more information 
about this technique, see "Configuring the message resources" in Chapter 6.) 



Listener configuration 

Application listeners are a new feature in the Servlet 2.3 specification. Their 
inclusion allows application developers to be aware of various servlet events 
regarding the Servl etContext and HttpSessi on objects. In particular, devel- 
opers can receive notification of lifecycle events for either object or changes 
to attributes stored in either object. 

The tag for defining a listener is<listener>. The syntax for the tag is 

<!ELEMENT listener ( 1 i stener-cl ass )> 
< ! ELEMENT listener-class (#PCDATA)> 

In this syntax, <listenerclass>is the fully qualified name of the Java class 
that implements one of the Listener interfaces. 

Following is an example of the tag's use: 

<1 i stener> 

<1 i stener-cl ass> 

com.othenos. purchasing. common. SessionManager 

</l i stener-cl ass> 
</l i stener> 

In the example we define one listener class named com.othenos. purchasing, 
common. SessionManager. The creation of an application listener class is 
more fully described in Chapter 9. 



ActionSeri/tet configuration 

In a Struts application, you always have at least one servlet to declare and 
possibly others. The servlet definition section of web . xml allows you to 
define many of the key features of the servlet, in particular the fully qualified 
class name and how the servlet will be referenced. 
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The tag that defines a servlet is<servlet>. The syntax for the tag is 
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ENT servlet (icon?, servl et-name , display-name?, 

cription?,(servlet-class|jsp-file), init-param*, 
ad-on-startup? , run-as?, security-role-ref*)> 
ELEMENT icon (smal 1 -icon? , 1 arge-i con? ) > 
ELEMENT servlet-name (#PCDATA)> 
ELEMENT display-name (#PCDATA)> 
ELEMENT description (#PCDATA)> 
ELEMENT servl et-cl ass (#PCDATA)> 
ELEMENT jsp-file (#PCDATA)> 

ELEMENT init-param (param-name, param-value, descri pti on? )> 
ELEMENT load-on-startup (#PCDATA)> 
ELEMENT run-as (description?, role-name)> 
ELEMENT securi ty- rol e- ref (description?, role-name, role- 
link?^ 



In this syntax, you use the following tags: 

i** <i con>: An optional tag that provides small and large icons to represent 
the Web application in a GUI tool. 

<servl et name>: Sets the name that refers to the servlet instead of the 
more verbose class name. 

<di spl ay name>: An optional tag that defines a short name intended to 
be displayed in GUI tools. 

<description>:An optional tag that provides descriptive text about 
the parent element. 

<servletclass>: Must define the fully qualified name of the servlet 
class. You must specify either this tag or the following jsp-file tag. 

< j s p - f i 1 e > : Must contain the full path to the JSP file beginning with / . 

V < i n i t - p a r a m > : An optional tag that contains one name-value pair that is 
passed to the servlet at initialization. The tag can be repeated multiple 
times. The requirements of the specified servlet determine the possible 
parameters. 

V <loadonstartup>:An optional tag that specifies to the Web container 
the order of loading and initializing the servl ets. Use a value of 0 or any 
positive integer to load the servlets in order from smallest integer to 
largest. Otherwise, the Web container can load the servlets in whatever 
order it wants. 

<run as>:An optional tag that overrides the security identity that this 
servlet used to call an Enterprise JavaBean (EJB). 

<securityroleref>:An optional tag that defines a mapping between 
the name of a role called from a servlet and the name of a security role 
defined for the Web application. 
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An example of servlet configuration follows: 
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*^ervl et-name>acti on</servlet-name> 
T^ervl et-cl ass>org. apache. struts. act i on. Act ionServlet 
</servl et-cl ass> 
<i ni t-pa ram> 

<param-name>config</param-name> 

<param-value>/WEB-INF/struts-config.xml</param-value> 
</init-param> 

<load-on-startup>K/load-on-startup> 
</servl et> 




You can supply numerous initialization parameters toActionServlet using 
the <i ni t-param> tag. 

When you specify the value of a parameter, you need to enclose it in quotation 
marks. 

Here is the current list of parameters: 



.J0KK 




conf i g: Context-relative path to the XML resource containing the config- 
uration information for the default module. This may also be a comma- 
delimited list of configuration files. Acti onServl et loads each file in 
turn, and its objects are appended to the internal data structure. The 
default is /WEB-INF/struts-config.xml. 

If you define an object of the same name in more than one configuration 
file, the last one loaded wins. 

conf i g/${modul e}: Context-relative path to the XML resource containing 
the configuration information for the application module that will use the 
specified prefix (/$ { modul e )). You can repeat this as many times as you 
need for multiple application modules. 

V convertNul 1 : Forces simulation of the Struts 1.0 behavior when popu- 
lating forms. If set to true, the numeric Java wrapper class types (such 
as java.lang. Integer) default to null (rather than 0) . The default is 

f al se. 

f" rul esets: Comma-delimited list of fully qualified class names of addi- 
tional org .apache . commons . di gester . Rul eSet instances that should 
be added to the Di gester that will be processing struts -conf i g . xml 
files. By default, only the Rul eSet for the standard configuration elements 
is loaded. 

val i dati ng: Uses a validating XML parser to process the configuration 
file (strongly recommended). The default is true. 
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ActionSertftet mapping 



let mapping tag defines the mapping between a URL pattern and a 
ith it, the Web container will recognize that the servlet is responsi- 
ble for handling all requests that follow the specified URL pattern. 

The tag that defines the servlet mapping is <servlet-mapping>. The syntax 
for the tag is 

<!ELEMENT servl et-mappi ng ( servl et-name , url -pattern)> 
< ! ELEMENT servl et-name (#PCDATA)> 
< ! ELEMENT url -pattern (#PCDATA)> 

In the syntax for the servlet mapping tag, you use the following items: 

is* <servlet-name>: Refers to the name that you gave the servlet when 
you defined it using the <servl et> tag. (For more information, see the 
"ActionServlet Configuration" section.) 

i>* < u r 1 - p a 1 1 e r n > : Specifies the URL pattern to associate with the servlet 
name used in <servlet name>. 



An example of servlet mapping follows: 



<servlet-mapping 


> 






<servl et-name>acti on</servlet-n 


ame> 




<url -pattern 


>* . do</url -pattern) 







</servl et-mappi ng> 



This servlet mapping informs the Web container that any URL that ends in 
.do should pass to the servlet whose name is action. You can use any pat- 
tern, but * . do is common in Struts applications. The servlet associated with 
the name action was defined by the <servlet> tag in the preceding section 
of this chapter. 



Addinq in the taq libraries 

You need to define tag libraries, like the ones that are part of the Struts-EL 
package, in the web . xml file so that the application can use them. 

To define tag libraries, use the <tag1 i b> tag. The syntax for the tag is 

< ! ELEMENT tagl i b (taglib-uri, tagl i b- 1 ocati on )> 

< ! ELEMENT taglib-uri (#PCDATA)> 

< ! ELEMENT ta gl i b - 1 ocati on (#PCDATA)> 
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In this tag, you use the following items: 
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1 i b-uri >: Describes a URI, relative to the location of the web . xml 
ment, identifying a tag library used in the application. This URI will 
be used in the JSP page to reference the tag library. 



I <taglib-location>: Contains the location (as a resource relative to the 
root of the Web application) of the Tag Library Description file for the tag 
library. 

An example of the use of the <tagl i b> follows: 

<tagl ib> 

<tagli b-uri >jstl-c</tagli b-uri > 

<tagl ib-location>/WEB-INF/c.tld</tagl ib-1 ocation> 
</tagl ib> 

This example defines the location of the Tag Library Descriptor as /WEB- INF/ 
c . tl d and defines / jstl -c as the URI to use to reference the taglib in a JSP 
page. 

Then in the JSP page, you reference the ta gl i b as follows: 

<7o@ taglib prefix="c" uri = "jstl-c" %> 

The sequence of tags in an XML document is important and must be followed. 
For example, in the web . xml file, you can't define the <servl et mappi ng> tag 
before you define the <servlet> tag. If you have configuration errors at startup 
time, be sure to check the sequence of your tag definitions. Make sure they 
follow the sequence that you defined in the DTD for the XML file in question. 



A complete example of a utebjml file 

Listing 7-1 is a complete example of a web . xml file taken from the 
MusicCollection application we build in Chapter 14. 

Listing 7-1 A Complete Example of a web.xml File 

<?xml vers i on=" 1.0" encoding="IS0-8859-l"?> 

<! DOCTYPE web-app 
PUBLIC "-//Sun Microsystems, Inc. //DTD Web Application 2.2//EN" 
"http://java.sun. com/j2ee/dtds/web-app_2_2.dtd"> 

<web-app> 



(continued) 
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Listing 7-1 (continued) 
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<^-;_Action Servlet Configuration --> 
~\let> 

'ervl et-name)acti on</servl et-name> 
<servlet-class>org. apache. struts . acti on . Acti onServl et</servl et-cl ass> 
<init-param> 
<param-name>config</param-name> 

<pa ram- va 1 ue)/WEB- INF/struts -confi g.xml</pa ram- val ue) 
</init-param> 

<load- on -startup) K/load- on -startup) 
</servl et) 



<!-- Action Servlet Mapping --) 
<servl et-mappi ng) 

<servl et-name)acti on</servl et-name) 

<url - pa ttern)*.do</url -pattern) 
</servlet-mapping) 

<!-- The Welcome File List --) 
<wel come-f i 1 e-1 i st) 

<wel come-f i 1 e)home. jsp</wel come-f i 1 e) 
</welcome-file-list) 

<!-- JSTL Tag Library Descriptor --) 
<taglib> 

<taglib-uri)jstl-c</taglib-uri) 

<tagl i b- 1 oca t i on)/WEB- 1 NF/c.tld</taglib- location) 
</taglib> 



<taglib) 

<tagl ib-uri)jstl-fmt</taglib-uri) 
<tagl i b- 1 oca t i on)/WEB- 1 NF/fmt.tld</taglib- location) 
</taglib> 



<!-- Struts Tag Library Descriptors --> 
<taglib) 

<tagl ib-uri)/WEB- INF/struts- bean-el. tld</taglib-uri) 
<taglib-location)/WEB-INF/st ruts- bean-el. tld</taglib-locati on) 

</taglib) 



<taglib> 

<taglib-uri)/WEB- INF/struts -html -el .tld</taglib-uri) 
<tagl i b-1 ocati on)/ WEB- INF/struts -html -el.tld</taglib-location) 
</taglib> 



<taglib> 

<tagl ib-uri)/WEB- INF/struts - 1 ogi c-el .tld</taglib-uri) 
<tagl i b-1 ocati on)/WEB- INF/struts -1 ogi c-el . tld</tagl i b-1 ocati on) 
</taglib> 



</web-app) 
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Modifying the Stmts Configuration File 

1 1^ I J ^) ^^tje^^^s configuration file, struts -confi g . xml , is similar to the web . xml 

confie 



configuration file for the Web container except that it informs the Struts 
framework about the components the developer is adding to the framework 
and how to use these components. 

The struts confi g . xml file, like web . xml , has a DTD file that defines the 
acceptable grammar for laying out the configuration. Each struts-config. 
xml file must begin with a DOCTYPE indicating the version of the DTD to use. 
The following example specifies version 1.1 of the Struts Configuration DTD: 

<!D0CTYPE struts-config PUBLIC "-//Apache Software 

Foundati on//DTD Struts Configuration 1.1//EN" 

" http : // j a karta. apache. org/struts /dtds/struts- 
conf i g 1 1 . dtd"> 

The root tag of the struts -confi g. xml file is <struts - confi g>. The 
<struts- confi g> tag is always the first tag in the struts -confi g. xml file. 
The following code defines the use of this tag and all the possible other tags 
in it. The DTD syntax for the struts-config tag is shown here: 

<!ELEMENT struts-config (data -sources? , form-beans?, 
gl obal -excepti ons? , gl obal -forwards? , action-mappings?, 
controller?, message-resources*, plug-in*)> 

We show a complete example ofastruts config file at the end of this 
section. 



DataSource confirmation 

The Struts framework can take direct advantage of implementations of the 
javax.sql .DataSource interface to provide database connections and pool- 
ing for Web applications. Some Web container providers or database vendors 
may offer a pooling mechanism that implements the javax.sql .DataSource 
interface. Such a mechanism might be your first choice. If not, take a look 
at the Jakarta Commons DBCP package as a possibility. This package is a 
DataSource implementation and offers connection pooling when you use it 
with the Jakarta Commons Pool package. For more information about 
DataSources, see Chapter 5. 

If you must support more than one database, you can enter each database as 
a datasource in the datasources configuration. The tag for inserting data- 
sources is <data sources>. The DTD syntax for the tag follows: 
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<!ELEMENT data-sources (data-source*)> 
[ELEMENT data-source (set-property*)) 

!JrTj#HkIST data-source className %C1 assName ; #IMPLIED> 
f\I^IST data-source key XAttri buteName ; #1 MPLI ED> 

<!ATT1IST data-source type XClassName; #1 MPLI ED> 



< ! ELEMENT set 
< ! ATTLIST set- 
<!ATTLIST set 



property 
property 
property 



EMPTY) 
property 
val ue 



XPropName ; 
CDATA 



^REQUIRED) 
^REQUIRED) 



In this tag, you use the following two tags, each with a set of attributes that 
follow: 



<data source>: Defines the datasource implementation and the key 
that references it. 

• cl assName: The configuration bean for this DataSource object. If 
specified, the object must be a subclass of the default configura- 
tion bean. The default is org . apache .struts . conf i g . 
DataSourceConf i g. 

• key: Servlet context attribute key that locates this datasource. The 
default is org . apache .struts . acti on . DATA_SOURCE. In our 
examples we use the application name, such asmusiccollection. 
The application module prefix (if any) is appended to the key 

($ { key ) $pref i x)). 

The application module prefix includes the leading slash. For exam- 
ple, the musiccollection datasource key for a module named 

fooismusiccollection/foo. 

• type: Fully qualified Java class name for this datasource object. The 
class must implement DataSource [javax.sql .DataSource], and 
the object must be configurable entirely from JavaBean properties. 

1* <set property>: Provides a series of name-value pairs that you can use 
to initialize the datasource. 

• property: Name of the JavaBeans property whose setter method 
will be called. 

• val ue: String representation of the value to which this property 
will be set, after suitable type conversion. 

Your choice of parameters depends on the datasource implementation that you 
choose to work with. If you're using the Commons DBCP package, for example, 
look at Jakarta. apache . 0 rg /commons /dbcp/ conf i gurati on . html for 
details of the properties you can set. 
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Listing 7-2 shows an example of the tag's use for the Commons DBCP taken 
from the example application in Chapter 14. 



1 



-2 Using the data-sources Tag for the Commons DBCP Package 

<data-sources> 

<data -source key="musi ccol lection" 

type=" org. apache. commons .dbcp.BasicDataSource"> 
<set-property property="description" 

Music Collection Database"/> 
property="driverClassName" 
com.mysql . jdbc . Dri ver" /> 
proper ty="username" value="root"/> 
property="password" val ue="bigmoma"/> 
property=" url " 

jdbc:mysql ://local host/musi ccollection" /> 
proper ty=" ma xCount" value="8"/> 
property =" mi nCount" value="2"/> 



<set- 



val ue 
property 
val ue= 
<set-property 
<set-property 
<set-property 
val ue= 
<set-property 
<set-property 
</data-source> 
</data-sources> 



In Listing 7-2, note the following: 



Line 1: Defines org. apache .commons .dbcp.BasicDataSource as the 
fully qualified class name of the implementation of the j avax . sql . 
DataSource interface. In addition, the example defines musi ccollection 
as the key to use to look up the datasource from the application scope. 

*** Lines 2-8: Defines the set of parameters to pass to the DataSource 
implementation. 



formbean configuration 



You need to define the formbean in the struts config file. We also discussed 
formbeans extensively in Chapters 3 and 6. 

The tag for inserting formbeans is <formbeans>. The DTD syntax for the tag 
follows: 



< ! ELEMENT 
< ! ATTLIST 


f orm- 
f orm- 


beans 
beans 


(form-bean*)> 

type %ClassName; 


#IMPLIED> 





<!ELEMENT form-bean (icon?, display-name?, description?, 

set-property*, f orm-property*)> 
<!ATTLIST form-bean className XClassName; #IMPLIED> 
<! ATTLIST form-bean dynamic "^Boolean; #IMPLIED> 

<! ATTLIST form-bean name %BeanName; #REQUIRED> 

<! ATTLIST form-bean type %C1 assName ; #REQUIRED> 
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ELEMENT 
ELEMENT 
,ENT 
|ENT 
ELFFlENT 
ELEMENT 
ATTLIST 
ATTLIST 
ELEMENT 
ATTLIST 
ATTLIST 
ATTLIST 
ATTLIST 
ATTLIST 



icon ( smal 1 -i con? , 1 arge-i con? ) > 
large-icon (%Locati on ; )> 
small-icon (%Locati on ; )> 
display-name (#PCDATA)> 
description (#PCDATA)> 
set-property EMPTY) 
set-property property XPropName; 
set-property value CDATA 
form-property (set-property*)> 
form-property className KlassName; 
form-property initial CDATA 
form-property name XPropName; 
form-property size ^Integer; 
form-property type KlassName; 



#REQUIRED> 
#REQUI RED> 

#IMPLIED> 

#IMPLIED> 

#REQUIRED> 

#IMPLIED> 

#REQUIRED> 



You use the following notation in the DTD file: 



<f orm beans>: Starts the section where all the formbeans are defined. 

<f orm bean>: Defines a formbean to be used in the application. The tag 
has the following attributes: 

• className: The configuration bean for this formbean object. If 
specified, the object must be a subclass of the default configuration 
bean. The default is org .apache . struts . conf i g . FormBeanConf i g. 

• dynami c: This attribute is deprecated. This information is now 
determined dynamically based on the specified implementation 
class. 

• name: The unique identifier for this form bean. Referenced by the 
<acti on> element to specify which formbean to use with its 
request. 

• type: Fully qualified Java class name of the Acti onForm subclass 
to use with this formbean. 

<i con>: Defines a large - icon orasmallicon or both that you can 
use to represent this formbean in a GUI tool. 

<di spl ay name>: Defines a name to be associated with this formbean in 
a GUI tool. 

<description>: Contains descriptive text about the formbean for dis- 
play in GUI tools. 

i>* <set property>: Allows you to pass parameters to the formbean. See 
the "DataSource configuration" section earlier in this chapter for more 
details on <set-property>. 
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<f orm property): Used when the formbean is a class or subclass of 
DynaActi onForm. The tag has the following attributes: 

cl ass Name: The configuration bean for this form property object. 
If specified, the object must be a subclass of the default configura- 
tion bean. The default is org . apache .struts . conf i g . 
FormPropertyConfig. 

initial: String representation of the initial value for this property. 
If you don't specify a value, primitives are initialized to zero and 
objects are initialized to the zero-argument instantiation of that 
object class. For example, Strings are initialized to " " . 

name: The name of the JavaBean property described by this 
element. 

size: The number of array elements to create if the value of the 
type attribute specifies an array but does not specify a value for 
the initial attribute. 

type: Fully qualified Java class name of the field underlying this 
property, optionally followed by [ ] to indicate that the field is 
indexed. 



Listing 7-3 shows an example of a formbean definition. 



Listing 7-3 A Formbean Definition 

<form-beans> 

1 <form-bean name="loginForm" 



2 type=" org. apache. struts . val idator.DynaVal i da tor Form") 

3 <form-property name="emai 1 " 

4 type=" Java . 1 ang . Stri ng" 

5 initial-""/) 

6 <form-property name="password" 

7 type="java.lang. String" 

8 initial-""/) 



9 </form-bean> 

... other form beans can be defined here 
</form-beans> 

Note the following sections of Listing 7-3: 

Lines 1-9: Define aDynaValidatorForm bean. 
I Line 1: Defines the name of the form to be 1 ogi nForm. 

Line 2: Indicates that the form is based on the DynaVal i datorForm class. 
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Lines 3-5: Specify that one property of the form is named emai 1 , of type 
String, with an initial value of " " . 



s 6-8: Specify that one property of the form should be named 
word, of type String, with an initial value of " ". 



Global exceptions 

You need to declare any global exceptions in the struts-config file. In this 
section, we discuss how to set up the configuration for global exceptions. For 
a full discussion of the ins and outs of declarative exception handling, see 
Chapter 8. 



The tag for inserting global exceptions is <gl 
syntax for the tag is 


obal -excepti ons> 


The DTD 


<!ELEMENT gl obal -excepti ons (except" 
<!ATTLIST gl obal -excepti ons id ID 

<!ELEMENT exception (icon?, display- 
set-property*); 
<!ATTLIST exception bundle S 
<!ATTLIST exception className ° 
<!ATTLIST exception handler 5 
<!ATTLIST exception key ( 
<!ATTLIST exception path 5 
<!ATTLIST exception scope ( 
<!ATTLIST exception type S 


on*)> 

#IMPLIED> 
name?, descripti 

> 

JAttri buteName ; i\ 
^ClassName; ]\ 
iClassName; i\ 
:data i\ 
JRequestPath ; )\ 
:data \\ 
iClassName; jj 


on? , 

IMPLIED) 

IMPLIED) 

IMPLIED) 

REQUIRED) 

IMPLIED) 

IMPLIED) 

REQUIRED) 


You use the following items for the global-exceptions tag: 





f <gl obal -excepti ons>: Marks the beginning of all global exception 
definitions. 



i>* <excepti on>: Starts the definition of one exception. The attributes of 
the tag follow: 

• bundle: Servlet context attribute for the message resources 
bundle associated with this handler. The default attribute is the 
value specified by the string constant declared at Gl oba 1 s . 

MESSAGES_KEY . The default is org . apache . struts . Gl obal s . 
MESSAGES_KEY . 

• cl assName: The configuration bean for this Excepti onHandl er 
object. If specified, cl assName must be a subclass of the default 
configuration bean. The default is org . apache .struts . conf i g 
Excepti onConf i g. 
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handler: Fully qualified Java class name for this exception handler. 
The default is org. apache, struts, act i on. Except ionHandler. 

key: The key to use with this handler's message resource bundle 
that will retrieve the error message template for this exception. 

path: The module-relative URI to the resource that completes the 
request and response if this exception occurs. 

scope: The context (request or session) that accesses the 
Acti onError object for this exception. The default is request. 

type: Fully qualified Java class name of the exception type to 
register with this handler. 



Here is an example of the tag's use: 



<gl obal -excepti ons> 

<exception bundle="Appli cat ion Re sources" 
key="error . Run ti me Excepti on" 
path="/baderror.jsp" 

handl er="dummi es. struts. music.CustomExcept ionHandler" 
type = " Java . 1 ang . Runti me Excepti on" /> 
</gl obal -excepti ons > 



The example describes one global exception of type Runti meExcepti on 
that supplies a message based in the error . RuntimeExcepti on resource 
bundle key The error is handled by a specialized exception handler class, 
CustomExcepti onHandl er. The destination is a custom error page named 

baderror . j sp. 



Global forwards 

Global forwards define a set of Acti onForwa rd objects available to all Acti on 
objects as a return value. Any Acti on Forwa rd of the same name that is defined 
in an <acti on> tag overrides the global Acti on Forward. 

The tag for inserting global forwards is < g 1 o b a 1 - f o r w a r d s > . The DTD 
syntax for the tag is 



< ! ELEMENT 
< ! ELEMENT 

< ! ATTLIST 
< ! ATTLIST 
<! ATTLIST 
<! ATTLIST 
<! ATTLIST 



gl obal 
forward 

forward 
forward 
forward 
forward 
forward 



forwards (forward*)) 
(icon?, di spl ay-name? , 
set-property*)> 



descri pti on? , 



cl assName 
contextRel a ti ve 
name 
path 

redi rect 



%C1 assName ; 
%Bool ean ; 
CDATA 

%RequestPath ; 
%Bool ean ; 



#IMPLIED> 
# I M P L I E D > 
#REQUIRED> 
#REQUIRED> 
#IMPLIED> 
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p b a 1 - f o r wa r d s > : Begins the definitions of one or more global 
ards. 



<forward>: Defines ActionForward. The attributes of the tag follow: 

• className: Fully qualified Java class name ofActionForward 
subclass to use for this object. The default is org. apache. struts. 
action.ActionForward. 

• contextRel ati ve: Set this to true if, in a modular application, the 
path attribute starts with a slash (/) and should be considered rel- 
ative to the entire Web application rather than the module. The 
default is f a 1 se. 

• name: The unique identifier for this forward. Referenced by the 
Action object at runtime to select — by its logical name — the 
resource that should complete the request/response. 

• path: The module-relative or context-relative path to the resources 
that this Acti onForward encapsulates. If the path is context-relative 
when used in a modular application, set the contextRel ati ve 
attribute to true. This value should begin with a slash (/) character. 

• redirect: Set to true if a redirect instruction should be issued to 
the user-agent so that a new request is issued for this forward's 
resource. If true, the sendRedi rect method of HttpServl et 
Response is called. If f al se, the f orwa rd method of Request 
Dispatcher is called instead. The default is false. 



An example of the tag's use is 

<gl obal -forwards) 

<forward name=" 1 ogon " 

path="/l ogon . jsp"/> 
</gl obal -forwards) 



This simple example sets up a global forward of the name "1 ogon " that for- 
wards control to the resource on the path " / 1 o g o n . j s p " . 



Action mapping 

Action mappings describe a set of Acti onMappi ng objects. Each Acti on 
Mappi ng object associates an Acti on object with a path and various other 
attributes. Exactly one Acti onMappi ng is represented by an acti on tag. 
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The tag for inserting actions is <action-mappings>. The DTD syntax for the 
tag is shown here: 



JENT acti 
1ST acti 



ELEMENT acti 



on -mappi ngs (action*)) 

on -mappi ngs type %ClassName; #IMPLIED> 



on 



(icon?, displ 
set-property 



ay-name?, description?, 
* exception*, forward*)) 



< 


ATTLIST 


acti 


on 


attri bute 


%BeanName ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


cl assName 


%C1 assName ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


forward 


%RequestPath ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


i ncl ude 


%RequestPath ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


i nput 


%RequestPath ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


name 


XBeanName ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


pa rameter 


CDATA 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


path 


%RequestPath ; 


#REQUIRED> 


< 


ATTLIST 


acti 


on 


pref i x 


CDATA 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


rol es 


CDATA 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


scope 


XRequestScope ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


suf f i x 


CDATA 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


type 


%C1 assName ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


unknown 


%Bool ean ; 


#IMPLIED> 


< 


ATTLIST 


acti 


on 


val idate 


%Bool ean ; 


#IMPLIED> 



The <acti on mappi ngs> tag uses the following attributes: 

i>* <acti on mappings): Defines the beginning of a set of actions. 

<acti on>: Represents one Acti onMappi ng object. The attributes of the 
tag follow: 

• attri bute: Name of the request-scope or session-scope attribute 
that accesses the ActionForm bean, if it's other than the bean's 
specified name. This attribute is optional if name is specified but 
otherwise is not valid. 

• cl assName: The fully qualified Java class name of the Acti on 
Mapping subclass to use for this action mapping object. Defaults to 
the type specified by the enclosing <acti on mappi ngs> element or 
to org .apache . struts . acti on .Acti onMappi ng if not specified. 

• forward: Module-relative path of the servlet or other resource that 
processes this request, instead of the Acti on class specified by 
type. You can specify one of the following: forward, i ncl ude, or 
type. 

• i ncl ude: Module-relative path of the servlet or other resource that 
processes this request, instead of the Action class specified by type. 
You must specify one of the following: f orwa rd, i ncl ude, or type. 
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i nput: Module-relative path of the action or other resource that 
gets control if a validation error occurs. Valid only if you specify 
the name attribute. If you specify the name attribute and the input 
bean returns validation errors, you must specify this attribute. On 
the other hand, if you specify the name attribute and the input 
bean does not return validation errors, this attribute is optional. 

• name: Name of the formbean, if any, associated with this action 
mapping. 

• path: The module-relative path of the submitted request, starting 
with a slash (/) character and without the filename extension if 
you are using extension mapping. 

Never include a period in your path name. Acti onServl et consid- 
ers a period the beginning of a filename extension and will not be 
able to locate your Acti on. 

• parameter: General-purpose configuration parameter that you can 
use to pass extra information to the Acti on object selected by this 
action mapping. 

• prefix: Prefix used to match request parameter names to 

Acti on Form property names, if any. Optional if you have specified 
the name attribute; otherwise, the prefix attribute is not allowed. 

• roles: Comma-delimited list of security role names that are 
allowed access to this Acti onMappi ng object. 

• scope: The context (" request" or " sessi on ") used to access 
the ActionForm bean, if any. This attribute is optional if you spec- 
ify the "name" attribute; otherwise, it's not valid. 

• suffix: Suffix used to match request parameter names to 
ActionForm bean property names, if any. This attribute is optional 
if you specify the name attribute; otherwise it's not valid. 

• type: Fully qualified Java class name of the Acti on subclass [org . 
apache. struts. act ion. Act ion] that will process requests for 
this action mapping. This attribute is not valid if you have specified 
the f orwa rd or i ncl ude attribute. You must specify f orwa rd, 

i ncl ude, or type. 

• unknown: Set to true if this object should be configured as the 
default action mapping for this module. If a request does not match 
another object, it will be passed to the Acti onMappi ng object with 
unknown set to true. You can mark only one Acti onMappi ng as 
unknown in a module. The default is f a 1 se. 

• va 1 i date: Set to true if you want to call the va 1 i date method of 
the Acti onForm bean before calling the Acti on object for this 
action mapping. Set to f a 1 s e if you don't want to call the validate 
method. The default is true. 



Listing 7-4 shows an example of the <acti on-mapping) tag's use. 
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on -mappi ngs> 
tion path=" /home" 

type="dummi es. struts. mus i c . Log inAct ion" 

3 name=" 1 ogi nForm" 

4 scope=" request" 

5 i nput=" /home . jsp" 

6 val idate="true"> 

7 <forward name=" f ai 1 ure" path = "/home. jsp"/> 

8 <forward name="success" path=" /musi cl i st . do" /> 

9 <forward name="join" path = "/join . jsp"/> 
</acti on> 

</acti on-mappi ngs> 



Here's an explanation of Listing 7-4: 



Line 1 : Defines the path for this A c t i o n M a p p i n g as "/home". The actual 
URI used to invoke this action is / home . do because * . do was defined as 
the URL pattern in web . xml . 

V Line 2: Specifies that the Acti on class is POActi on and will be called for 
each request. 

i>* Line 3: Associates " 1 og i n Fo rm " as the formbean to be used with 
requests. 

i>* Line 4: Specifies that the formbean be stored in the request object. 

V Line 5: Indicates that control should be returned to home .jsp in the 
event of a validation error. 

Line 6: Calls the val i dati on method of the formbean. 
Lines 7-9: Define forwards to be used by the Acti on class. 



Controller configuration 



You can make changes in the configuration of the ActionServlet through 
the use of the control ler tag. You can configure quite a few qualities of the 
ActionServlet through this tag. Most applications can skip configuring the 
controller and simply use the default values. 

The tag for inserting a new controller is<controller>. The DTD syntax for 
the tag is shown here: 

<!ELEMENT controller (set-property*)> 

< ! ATTLIST controller bufferSize ^Integer; # I M P L I E D > 

< ! ATTLIST controller className KlassName; # I M P L I E D > 

<! ATTLIST controller contentType CDATA # I M P L I E D > 

<! ATTLIST controller debug ^Integer; #IMPLIED> 
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< 


ATTLIST 


control 1 er 


f orwardPattern 


CDATA 


#IMPLIED> 




ATTLI ST 


control 1 er 


i nputForward 


%Bool ean ; 


JL T m n i t r n \ 

# IMPLIED) 




A-T^ilST 


control 1 er 


1 ocal e 


%Bool ean ; 


#IMPLIED> 




\tHist 


control 1 er 


maxFi 1 eSi ze 


CDATA 


#IMPLIED> 




ATTLIST 


control 1 er 


memFi 1 eSi ze 


CDATA 


#IMPLIED> 


< 


ATTLIST 


control 1 er 


mul ti partCl ass 


%C1 assName ; 


#IMPLIED> 


< 


ATTLIST 


control 1 er 


nocache 


%Bool ean ; 


#IMPLIED> 


< 


ATTLIST 


control 1 er 


pagePattern 


CDATA 


#IMPLIED> 


< 


ATTLIST 


control 1 er 


processorCl ass 


%C~\ assName ; 


#IMPLIED> 


< 


ATTLIST 


control 1 er 


tempDi r 


CDATA 


#IMPLIED> 



The <control 1 er> tag defines any changes to Acti onServl et. The list of 
possible attributes is as follows: 



buf f erSi ze: The size of the input buffer used when processing file 
uploads. The default is 4096. 

cl assName: Fully qualified Java class name of the Control 1 erConf i g 
subclass for this controller object. If you specify this attribute, the object 
must be a subclass of the default class. The default is org. apache, 
struts. config.ControllerConfig. 

content Type: Default content type (and optional character encoding) 
for each response. The Action, JSP, or other resource that receives the 
request may override this attribute. The default is text/html . 

i>* debug: Debugging detail level for this module. The default is 0. This 
attribute is deprecated. Instead, you should configure the logging detail 
level in your underlying logging implementation. For more information 
on logging, see Chapter 13. 

forwardPattern: Replacement pattern defining how the p a t h attribute 
of a <f orward> element is mapped to a context-relative URL when it 
starts with a slash (and when the contextRel at i ve property is f al se). 
This value may consist of any combination of the following: 

• $M: Replaced by the prefix of this module. 

• $P: Replaced by the path attribute of the selected forward element. 

• $ $: Displays a literal dollar sign. 

• $x: x is any character not defined previously in this list. Currently 
disregarded, but reserved for future use. 

The default forwardPattern is $M$P. 

i nputForward: Set to true if you want the input attribute of <acti on> 
elements to be the name of a local or global ActionForward, which will 
then be used to calculate the ultimate URL. Set to fa 1 se to treat the 
input parameter of <acti on> elements as a module-relative path to the 
resource to be used as the input form. The default is f a 1 se. 

locale: Set to true if you want to store a Local e object in the user's 
session if not already present. The default is true. 



Chapter 7: Setting the Configuration 



acce 

ipBocfe 



j^maxFileSize: The maximum size (in bytes) of a file that the application 
accepts as a file upload. You can express this attribute as a number fol- 
d by a K, M, or G, for kilobytes, megabytes, or gigabytes, respec- 
y. The default is 250M. 



V memFi 1 eSi ze: The maximum size (in bytes) of a file whose contents are 
retained in memory after uploading. Files larger than this threshold are 
written to some alternative storage medium, typically a hard disk. Can 
be expressed as a number followed by a K, M, or G, for kilobytes, mega- 
bytes, or gigabytes, respectively. The default is 256K. 

i>*multipartClass: The fully qualified Java class name of the multipart 
request handler class that you want to use with this module. The default 

is org. apache. struts. upload.CommonsMulti part Re questHandler. 

f" nocache: Set to t r u e if you want the controller to add HTTP headers for 
tell the Web server not to cache responses from this module. The default 

is f al se. 

pagePattern: Replacement pattern defining the mapping of the page 
attribute of custom tags to a context-relative URL of the corresponding 
resource. This value may consist of any combination of the following: 

• $M: Replaced by the prefix of this module. 

• $ P : Replaced by the value of the p a g e attribute. 

• $ $: Displays a literal dollar sign. 

• $x: x is any character not defined previously in this list. This value 
is currently disregarded, but reserved for future use. 

The default pagePattern is $M$P. 

i>* processorCl ass: The fully qualified Java class name of the Request 
Processor subclass to be used with this module. The default is org. 
apache. struts. act ion. Re questProcessor. 

tempDi r: Temporary working directory to use when processing file 
uploads. The default is {Directory provided by servlet container}. 



An example of the tag's use is shown here: 

Controller processorCl ass = 

" com. othenos. purchasing. common . Custom RequestProcessor"/> 



This example shows the installation of a new RequestProcessor subclass. 
This replaces the original RequestProcessor reference in Acti onServl et. 



Message resource configuration 

To insert message resources, use the <message - resources) tag. For more 
information on message resources, their use and configuration, see Chapters 
3 and 6. 
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ma 

< ! ATTLIST 
< ! ATTLIST 
<!ATTLIST 



message-resources 
message-resources 
message-resources 
message-resources 
message-resources 
message-resources 



( set-property*)> 

className XCl assName ; #IMPLIED> 
factory KlassName; #IMPLIED> 
key MttributeName; #IMPLIED> 
null ^Boolean; #IMPLIED> 

parameter CDATA #REQUIRED> 



The <message resources> tag defines a message resource bundle to be 
made available to the Web application. The parameter attribute is required 
and refers to the file name of the resource bundle. The following are attrib- 
utes of the tag: 



cl assName: The configuration bean for this message resources object. If 
you specify this attribute, the object must be a subclass of the default con- 
figuration bean. The default is org .apache . struts . conf i g . Message 
ResourcesConf i g. 

factory: Fully qualified Java class name of the Message Re sources 
Factory subclass to use for this message resources object. The default 

is org. apache. struts. util .Property Message Re sources Factory. 

V key: Servlet context attribute key that locates the message resources 
bundle. The default attribute is the value that the string constant 
Gl oba 1 s . MESSAGES_KEY specifies, which happens to be org . apache . 
struts . acti on . ACTION_MESSAGE. The application module prefix (if 
any) is appended to the key ($ { key ) $ ( pref i x)). 

The application module prefix includes the leading slash. For example, 
org . apache . struts . acti on . MESSAGE/f oo references the default mes- 
sage resource bundle for a module named f oo. 

z>* null: Set to true if you want your message resources to return a null 
string for unknown message keys. Set to f al se to return a message with 
the bad key value in the form of ? ? ?key? ? ? . 

parameter: Configuration parameter to be passed to the create 
Resources method of the PropertyMessageResourcesFactory object 
or its subclass. 



Here is an example of the tag's use: 

<mes sage -resources nul 1 ="f al se" 

parameter="Appli cat i on Re sources "/> 

In this example, we specify a message resource bundle named "Application 
Resources". In addition, we specify that if a particular resource key can't be 
found, the application should display the " ? Ilkeyl 1 ? " message, as shown in 
Figure 7-1. 
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Figure 7-1: 

A message 
resource is 
missing, 
so the 
application 
displays lots 
of question 
marks. 
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PluqAn confirmation 

You can extend the functionality of Struts through the use of plug-ins, such as 
the Validator plug-in. We discuss the use of plug-ins fully in Chapter 9. To use 
plug-ins, the Struts framework must learn about them through the plug-in tag 
that you place in the struts -confi g file. 

The tag for inserting plug-ins is < p 1 u g - i n > . The DTD syntax for the tag is 

<!ELEMENT plug-in (set-property*)> 

< ! ATTLIST plug-in className %ClassName; #REQUIRED> 

The DTD syntax for the < p 1 u g - i n > tag has one attribute — < p 1 u g - i n > — 
that defines the plug-in that you want to include by requiring the className 
attribute. The cl ass Name attribute specifies the fully qualified Java class 
name of the plug-in class and must implement [org. apache. struts. 
action.Plugln]. Some plug-ins require parameters; others don't. If you 
need parameters, specify them by using the set -property tag. 



Here is an example of the tag's use: 



<pl ug-i n 

className=" org. apache. struts. validator.ValidatorPlugln") 
<set -property proper ty=" pathnames" 

va 1 ue=" /WEB-INF/validator-rules.xml , 
/WEB-INF/val idation.xml "/> 

</pl ug-i n> 



Part II: Starting from the Core 



DBodte 



In this example, we define the Validator plug-in. This plug-in requires one 
parameter, "pathnames". This parameter specifies the paths to find its con- 
files: validator-rules.xml and val i dati on . xml . 



Complete example of a 
stmtS'Confiqjmt file 



In this chapter, we've broken the struts-config.xml file into itty-bitty 
pieces to provide you with all the details you need. Now is the time to put 
Humpty Dumpty back together again. Listing 7-5 is a complete example of a 
working struts-config.xml file taken from the example application we 
create in Chapter 14. The comments in the file help to delineate all the sec- 
tions that we've discussed. 



Listing 7-5 A Complete Example of the struts-config.xml File 

<?xml vers i on=" 1.0" encodi ng=" ISO-8859-1 " ?> 

<! DOCTYPE struts-config PUBLIC 

"-//Apache Software Foundati on//DTD Struts Configuration 1.1//EN" 
"http://jakarta.apache.org/struts/dtds/struts-confi g_l 1 . d t d " > 

<!-- This is the Struts configuration file for Musi cCol 1 ecti on application --> 

<struts-config> 

<!-- ========== DataSource Definitions ================================= --> 

<data-sources> 
<data-source key="musi ccol 1 ecti on" 

type=" org. a pa che. commons. dbcp.BasicDataSource") 
<set-property property="descri pti on" value="Music Collection Database"/) 
<set-property property="dri verCl assName" value="com.mysql . jdbc . Dri ver"/> 
<set-property property="username" value="root"/> 
<set-property property="password" value="bigmoma"/> 
<set-property property="url " 

val ue=" jdbc:mysql : //l ocal host/musi ccol 1 ecti on" /> 
<set-property property="maxCount" val ue="8"/> 
<set-property property="mi nCount" val ue="2"/> 
</data-source> 
</data-sources> 

<!-- ========== Form Bean Definitions ================================= --> 

<form-beans> 
<form-bean name="l ogi nForm" 

type=" org. apache. st ruts. val idator.Dyna Validator Form") 
<form-property name="email" 

type=" Java . 1 ang . String" 
i n i t i a 1 = " " / > 
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type="java . lang.String" 
i n i t i a 1 = " " / > 



rm-bean> 



<form-bean name=" joinForm" 

type="org . apache . struts .validator.DynaVal idatorForm") 
<form-property name="emai 1 " 

type="java. lang.String" 

<form-property name="password" 

type="java. lang.String" 

Initial-""/) 
<form- property name="password2" 

type="java. lang.String" 

i n i t i a 1 = " " / > 
<form-property name="fname" 

type="java. lang.String" 

initial-""/) 
<form-property name="lna[ne" 

type="java. lang.String" 

initial='"7) 

</form-bean> 



<f orm-bean name="musi cl i stForm" 

type="org .apache.struts.action. DynaActi on Form") 
<form-property name="acti on" 

type="java. lang.String" 
i n i t i a 1 = " " / > 

</form-bean> 



<form-bean name="al bumForm" 

type=" org. apache. st ruts. val idator.DynaValidatorForm") 
<form-property name="al bum" 

type="java. lang.String" 

i n i t i a 1 = " "/ > 
<form-property name="arti st" 

type="java. lang.String" 

initial-""/) 
<form-property name="year" 

type="java. lang.String" 

initial-""/) 
<form-property name="type" 

type="java. lang.String" 

initial-""/) 
<form-property name="category" 

type="java. lang.String" 

initial-""/) 
<form- property name="descri pti on" 

type="java. lang.String" 

initial-""/) 

(continued) 
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<form-property name="userid" 

type="java.lang. String" 
initial-""/) 
<form-property name="id" 

type=" j ava . 1 ang . String" 
initial-""/) 
<form-property name="actionl" 

ty pe=" j a va . 1 ang . String" 
initial=""/> 
<form-property name="years" 
type : 

<form-property name 
type 

<form-property name 
type 

</form-bean> 
</form-beans> 



java.util .ArrayList" /> 
types" 

java.util .ArrayList" /> 
categories" 

java.util .ArrayList" /> 



<!-- ========== Global Exception Definitions ====================== 

<!-- key value will be taken from the Modul eExcepti on instance --> 
<gl obal -excepti ons> 
<excepti on bundl e = " A p p 1 i cat i on Resources" 
key="" 

path="/error. jsp" 

handler="dummies.struts.music.CustomExceptionHandler" 
type=" org. apache. st ruts. uti 1 .Modul eExcepti on" /> 
<excepti on bundl e = " A p p 1 i cat i on Resources" 
key=" error . Run time Excepti on" 
path="/baderror . jsp" 

handler="dummies.struts.music.CustomExceptionHandler" 
type=" java . 1 ang. RuntimeException" /> 
</gl obal -excepti ons> 



<!-- ========== Action Mapping Definitions ============================== --> 

<acti on-mappi ngs> 
<action path="/home" 

type=" dummies .struts .musi c . Logi nActi on" 
name="loginForm" 
scope="request" 
i nput=" /home -jsp" 
val idate="true"> 
<forward name="fai 1 ure" path="/home. jsp"/> 
<forward name="success" path="/musiclist.do"/> 
<forward name="join" path="/join.jsp"/> 
</action> 

<acti on path="/join" 

type="dummi es . struts .musi c. Joi nActi on" 

name=" joi nForm" 

scope="request" 

input="/join.jsp" 

val idate="true"> 
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<forward name="cancel " path="/home. j s p " / > 
<forward name="fai 1 ure" path="/join.jsp"/> 
orward name="success" path="/wel come. jsp"/> 
it i o n > 

<aTtion path="/musi cl i st" 

type="dummi es . struts .musi c.Musi cLi stActi on" 
name="musi cl i stForm" 
scope="request" 
input="/musiclist.jsp" 
validate="false"> 
<forward name="l ogoff " path="/l ogoff .do"/> 
<forward name="newal bum" path=" /al bum . do" /> 
<forward name="success" path="/musiclist.jsp"/> 
</acti on> 

<acti on path=" /al bum" 

type="dummi es . struts .music. Al bumActi on" 

name="al bumForm" 

scope="request" 

nput="/al bum. jsp" 

validate="false"> 
<forward name="cancel " path="/musiclist.do"/> 
<forward name="success" path="/musiclist.do"/> 
<forward name="new" path="/album.jsp"/> 
<forward name="fai 1 ure" path="/album.jsp"/> 
</acti on> 

<acti on path="/l ogoff" 

type="dummi es. struts. musi c. Logoff Act i on" 

scope="request" 

validate="false"> 
<forward name="success" path="/home. jsp"/> 
</action> 



</acti on-mappi ngs> 



<!-- ========== Controller Definition ============================== --> 

<control 1 er processorCl ass="dummi es . struts .musi c .CustomRequest Process or" /> 

<!-- ========== Message Resources Definitions =========================== --> 

<mes sage- resources nul l="fal se" 

parameter="Appl i cat i on Resources"/) 

<!-- ========== piugin Definitions =========================== --> 

<plug-in className="org. apache. struts. val i da tor. Validator PI ugln"> 
<set-property pr ope rty=" pathnames" 

val ue="/WEB-INF/val idator-rules.xml ,/WEB-INF/val idation.xml "/> 

</plug-in> 

<plug-in cl assName="dummi es . struts. music. StartupManager" /> 
</struts-conf i g> 
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In this part . . . 

JL/art III provides you with all the pieces that you need 
V to complete your Struts-enabled Web application. 
Chapter 8 deals with exception handling. Chapter 9 covers 
a number of useful plug-ins that can streamline your work. 
Chapter 10 explains the Struts tag libraries and how to 
use them. Chapter 1 1 is all about page composition tech- 
niques. Last but not least is Chapter 12, which explains 
the tools in Struts for securing your application. 
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In This Chapter 

Understanding the Java exception mechanism 

Choosing an exception strategy 

Writing Exception classes 

Using chained exceptions 

Asserting yourself 

Handling exceptions on your own 

Using Struts declarative exception handling 

Extending the Struts default exception handler 

Handling RuntimeExcepti ons 



IX ou may be the eternal optimist, but sooner or later all applications have 

problems (generally both sooner and later). These problems could be 
the result of actions outside your responsibility (for example, a network fail- 
ure), or they may be the result of coding errors. Regardless of the degree of 
effort made to eliminate errors, they do appear — even in the best software 
products. Therefore, you need to have a plan in place to react to errors as 
they occur so that the application can recover and continue to function prop- 
erly or, at the very least, shut down in a graceful way. 

You can find interesting statistics on how many programming errors occur 
per 1000 lines of code (KLOC). In a recent article in Software Development, 
Watts Humphry, the father of the Capability Maturity Model (CMM) (see 
www .sei.cmu.edu/tsp/watts-bio.html) described the average number of 
bugs found in various organizations that are certified at one of the five CMM 
levels (see www . sei . emu . edu/emm/emm. sum . html). The lowest-ranking 
CMM organizations (level 1) have no formal development process in place. 
The highest ranking CMM organizations (level 5) have the most mature and 
organized development process in place. Level 1 organizations averaged 7.5 
defects per KLOC, whereas level 5 averaged 1.05 per KLOC. 

Fortunately, you're programming in Java, which has an excellent problem 
notification and handling mechanism built in. 
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that can occur in Java are defined in a class hierarchy with the 
Throwabl e class as the king. The Throwabl e class has two subclasses: the 
Error class and the Excepti on class. See Figure 8-1 for an abbreviated class 
hierarchy. 



Figure 8-1: 

Java 
Throwable 
class 
hierarchy. 
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The Error class and its descendents (at least 25 subclasses) represent seri- 
ous errors from which recovery is not an option. The application should not 
try to handle these types of errors because they're usually outside the scope 
of the application and typically indicate a problem in the Java Virtual 
Machine (JVM). 

The Excepti on class and its descendents (at least 55 subclasses) represent 
errors that the application should make an attempt to handle. The Excepti on 
class has two lineages: the lOException and the Runti me Except ion classes. 

The Excepti on class, the IOExcepti on class, and its descendents make up 
the checked exceptions. With a checked exception, the application programmer 
must catch the exception in a try /catch block or throw (cause) a similar 
exception. The compiler insists upon it! Every other descendent of the 
Throwable class falls into the category of an unchecked exception. 



Try/catch block 

Inatry/catch block, the try block contains the code that may throw a 
checked exception. The catch block contains the reference to the exception 
that could be thrown. The catch block contains also the code that reacts to 
the exception. Here is an example of a simple try /catch block: 
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,me code that could throw the Excepti onType 
Excepti onType e) 
handle the exception here 



If your code in the t ry block performs some action that causes an exception 
to be thrown, control moves immediately to the code in the catch block. 

You're not required to catch unchecked exceptions. However, if they're not 
caught, your application terminates. The unchecked exceptions descended 
from the Error class should not be caught, because they're not recoverable 
anyway. However, the Runti meExcepti on class and its descendents should 
be caught. Later in this chapter, we show a mechanism uses Struts to catch 
the infamous Runti meExcepti on and it descendents. 



Throu/ing exceptions 

Methods throw checked exceptions when 

An error condition occurs in the code and the method can not or will 
not recover from it. 

An exception is thrown by a called method and the calling method can 
not or does not want to handle it. 

To let the compiler know that the method may throw an exception, the 
method specifies in the throws clause the type of exception(s) it might 
throw. For example, the following code illustrates a method that might throw 

an IOExcepti on: 

public void getTransf ers ( Stri ng token) throws IOException 
{ 

some code . . . 

) 

If certain conditions arise, the method may throw an IOExcepti on in the 
code by creating an instance of the exception and then use the throw key- 
word to actually throw it. Here's the preceding example illustrating how this 
might be accomplished: 

public void getTransf ers ( Stri ng token) throws IOException 
{ 

some code . . . 



Part III: Expanding Your Development Options 



DBooks 



// oops, some condition occurred which makes 
// us want to throw an exception 
(some condition) 

throw new IOExcepti on ( ) ; 



some further code 



The method can also call another method that throws an IOExcepti on. 
Rather than catching the exception, this method simply passes the exception 
up the call chain to the next method. 



Wrapping it up in finally 

What happens if you absolutely positively have to do something regardless 
of whether or not an exception is thrown? You can use a third block for that 
purpose called the finally block, which can be used only in the try / catch 
block. The finally block is guaranteed to always execute regardless of 
whether or not an exception was thrown. 

To see how you might use the final 1 y block, suppose that you're perform- 
ing some database operation in the try block that throws a SQLExcepti on. 
Before making the database call, you get a database connection. You want to 
release the connection under all circumstances; otherwise it is a nonrecover- 
able resource. Listing 8-1 shows some code that doesn't guarantee that the 
connection will always be released. 



Listing 8-1 A try/catch Block in Need of a finally Block 

1 public Map getCompaniest ) throws ModuleException 

2 ( 

3 HashMap companies = null; 

4 Connecti on conn = null; 

5 try 

6 I 

7 conn = dbConnMgr.getConnection( ) ; 

8 DBFactory dbf = DBFactory . getDBFactoryt ) ; 

9 DBUtility dbu = dbf . getDBUti 1 i ty( ) ; 

10 companies = dbu.getCompanies(conn) ; // retrieve companies from database 

11 conn. closet ) ; 

12 ) 

13 catch (SQLException se) 

14 { 

15 ModuleException me = new ModuleExcepti on( "error .company . sel ect" ) ; 

16 throw me; 

17 ) 

18 return companies; 

19 I 
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You do not have to understand the details of this code, just the fact that in 
the try block (lines 5-12), we are getting a database connection and then 
some operations that could throw aSQLException. Here's the 
if the code in lines 7-10 throws the exception, the release of the 
connection in line 1 1 would not take place. The connection would be left in 
limbo, so to speak. 



To circumvent this situation, you can add a f i na 1 1 y block to the code, 
which is guaranteed to always execute no matter what happens (unless the 
program exits). The code in Listing 8-2 has the finally block added. 

Listing 8-2 A try/catch Block Using a finally Block 

1 public Map getCompanies( ) throws ModuleException 

2 I 

3 HashMap companies = null; 

4 Connecti on conn = null; 

5 try 

6 I 

7 conn = dbConnMgr.getConnection( ) ; 

8 DBFactory dbf = DBFactory . getDBFactoryt ) ; 

9 DBUtility dbu = dbf . getDBUtil i ty( ) ; 

10 companies = dbu.getCompanies(conn) ; // retrieve companies from database 

11 ) 

12 catch (SQLException se) 

13 ( 

14 ModuleException me = new ModuleExceptiont "error. company. select"); 

15 throw me; 

16 ) 

17 finally 

18 { 

19 try 

20 ( 

21 conn. closet ) ; 

22 ) 

23 catch(SQLException se) 

24 { 

25 log.errorC'Could not close the connection. " + se.getMessage( ) ) ; 

26 ) 

27 ) 

28 return companies; 

29 ) 



We moved the line of code that releases the connection from the try block to 
the finally block (line 21). This example is a more complex than usual 
because executing line 2 1 (c o n n . c 1 o s e) could also result in aSQLException 
being thrown. Therefore, we have to wrap the line in a try /catch block also. 
Generally, statements in the finally block do not cause exceptions. 
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exceptions in Java. For more detail information on Java Exceptions visit the 
rial at 
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java.sun.com/docs/books/tutorial/essential/exceptions/index.html 
Another good article on exceptions is at 
www. devel oper . com/ Java /art i cl e . php/10922_1455891_l 



Exception Strategies 



Dealing with exceptions is an important part of creating robust applications 
(Web or otherwise). So you need to have a good strategy in place for those 
times when things don't go according to plan. In this section, we talk about 
ways of handling those "oops" situations. 



Catching exceptions 



Don't just have an empty catch block to satisfy the compiler. Do something 
useful. Exceptions are your friends. They're messengers that bring you valu- 
able information about the cause of trouble. It's a good idea is to extract the 
information out of the exception and save it somewhere, such as to the system 
console or a log file. We talk in more detail about logging in Chapter 13. 

Here are some useful possibilities for the catch block: 

Extract and save the relevant information from the exception 

f* Throw a new exception more relevant to your application 

Throw a new exception, chaining the original exception to the new one 
(see "Using Chained Exceptions") 



Exception information 



Every exception contains at least two pieces of valuable information that you 
can extract. The first is the detailed message describing the exception. You 
can get this by the method call getMessage: 

String theMessage = excepti on . getMessage( ) ; 



The second piece of information in every exception is the stack trace, which 
provides you with the calling history from the current method to the method 
that started the process. You can retrieve this information in a couple of ways. 
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The easiest way is just to use the pri ntStackTrace method, which outputs 
the trace to the standard error device (usually the Java console). 



ion.printStackTraceO; 
Following is a typical stack trace output: 

java.lang.Ill ega 1 Argument Except i on : Invalid context path: webpurchasing 
at org.apache.catal ina. core. StandardHostDepl oyer. remove 

(StandardHostDepl oyer Java : 458) 
at org.apache.catalina.core. StandardHost . remove(StandardHost . Java : 852 ) 
at org. apache. catalina.startup.HostConfig.undeployApps(HostConfig. java: 758) 
at org.apache.catalina.startup.HostConfig.stop(HostConfig.java:738) 
at org.apache.catalina.startup.HostConfig.lifecycleEvent 

(HostConfig.java:360) 
at org.apache.catalina.util.Li fecycl eSupport .fireLifecycle Event 

( Li fecycl eSupport .Java : 166) 
at org.apache.catalina.core.ContainerBase. stop(ContainerBase. java : 1221 ) 
at org.apache.catalina.core.ContainerBase.stop(ContainerBase.java:1233) 
at org.apache.catalina.core.StandardService.stop(StandardService.java:554) 
at org.apache.catalina.core.StandardServer.stop(StandardServer.java:2225) 
at org. a pa che.catalina. startup. Catalina.starttCatalina. java: 543) 
at org. a pa che.catalina. startup. Catal i na . execute( Catal i na . java : 400 ) 
at org. a pa che.catalina. startup. Catal ina. process(Catal ina. java: 180) 
at sun. reflect. Nati veMethodAccessorlmpl . i nvoke0( Nati ve Method) 
at sun. reflect. NativeMethodAccessorlmpl .invoke 

(Nati veMethodAccessorlmpl . java : 39) 
at sun. reflect. Del egatingMethodAccessorlmpl .invoke 

(DelegatingMethodAccessorlmpl .java: 25) 
at java. lang. reflect. Me thod.invoke( Me thod.java:324) 
at org.apache.catal ina.startup.Bootstrap.maint Bootstrap. java: 203) 



If you're not using the pri ntStackT race method (maybe because you're 
using a log file), you can still output the stack trace information programmati- 
cally. See the logExceptionChain method defined in Listing 8-3 for an exam- 
ple of how to do this. 

Some exceptions may have additional pieces of information available (such 
as. SQLExcepti on), so be sure to check the exception's API. You can find this 
in the Java API documentation under the java. lang. Except ion class. 



Writing \lour Ou/n Exception Classes 

Sometimes the members of the Throwable class hierarchy may not adequately 
describe the type of exception that your code needs to throw. For example, 
you may be expecting a list to be of a particular length. When you find that 
it's not the proper length, what exception do you throw? 10 Except ion? 
NoSuch Fi el dExcepti on? In looking through the 55 or so possibilities, you 
may find that none of them describe your particular error. In this instance, it 
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makes more sense to create your own exception class by extending Exception 
rather than use an exception that inadequately describes the situation. 



grammers think it's better to create an exception class by extending 
Exception, because it's unchecked and would, therefore, not require 
a try /catch block or a throws clause in the method signature. However, this 
technique is frowned upon because the compiler will not complain if you do 
not try to catch the exception (and possibly recover). A better idea is to 
extend one of the checked exceptions: Except ion, IOException,or one of 
its descendents. 



Struts provides one specialized exception class, Modul eExcepti on. This 
exception creates and stores anActionError instance using the key that 
you pass to the constructor. Act ion Error comes into play when Except ion 
Handler recognizes that the exception is an instance of Modul eExcepti on. 
Excepti onHandl er retrieves Acti onError directly from Modul eExcepti on. 
If the exception is not an instance of Modul eExcepti on, Excepti onHandl er 
creates an Acti onError instance based on the key in the exception declara- 
tion and the message found in the exception. (We discuss Excepti onHandl er, 
a Struts class for exception handling, in the "Declarative Exception Handling" 
section later in this chapter.) 



Usinq Chained Exceptions 

The chained exception mechanism is a new feature starting with Java version 
1.4. You can think of it as exception piggy-backing. One exception may contain 
another exception. Why would you want to use chained exceptions? It may 
be that your code has caught an exception of one type (say SQLException), 
but doesn't handle the exception other than to log it. Instead, it throws a new 
exception (say Excepti on). Normally, this means that all the information 
included inSQLException (for example, the stack trace) is lost when the 
new Excepti on is thrown. However, starting with Java version 1.4, you have 
the option of chaining the original exception with the new one. 

In the following example, when constructing the Excepti on, we can add 
SQLExcepti on to it, thereby chaining SQLExcepti on to Excepti on. Here is a 
code snippet showing how to do this: 

catch (SQLException se) 
( 

Exception e = new ExceptionC'A database error 

occurred" , se ) ; 
throw e; 

) 

In the Excepti on constructor, the "A database error occurred" string is 
the message associated with Excepti on and se is the cause. 
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That's nice, but what can you do with it? You don't have to do anything. 
However, when handling an exception, you now have the option of finding out 
eiha^it contains any additional chained exceptions. A new method in the 
fyi&y e hierarchy is getCause, which returns the Throwabl e that caused 
the current Throwabl e. This means you can programmatically retrieve the 
entire history of the exception and output the information to a log or system 
console. See the 1 ogExcepti onCha i n method in Listing 8-3 for an example of 
how to retrieve chained exception information. 

A helpful article on the chained exceptions feature of Java version 1.4 can be 
found at 

javabouti que. i internet. com/tutor i a 1 s/Chai ned_Excepti ons 



Asserting \lourself 

Another form of defensive programming is the use of assertions. Assertions can 
be characterized as lazy exceptions, in the sense that an assertion behaves 
somewhat like an exception yet takes a lot less code on the part of the pro- 
grammer. The following example clarifies this technique. Suppose that you've 
written a method that gets a reference to a poLi st object and then uses the 
reference to update information in the list: 

public void updateLi st( ) 
( 

... do something here to get a reference to a poList 
object 

// assert that we actually got the reference to poList 
assert poList ! = nul 1 ; 

... continue on with processing the poList 

) 

Under almost all conditions, you will get the reference (in this example, to a 
poList object) successfully. To cover the unlikely possibility that you can't 
get the reference, you assert that poList should not be null at this point. If it 
turns out to be null, an Assert ionError is thrown. 

The assert statement has two forms. The first form is as follows: 

assert expression!.; 
where express ionl evaluates to a boolean. The second form is 

assert expression!. : expression2; 
where express ion2 evaluates to a value. 
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difference between these two forms is that the first form throws 
t o r without any message, but the second form uses express i o n 2 
ssage in AssertError. 

npiling code with assertions, you must have JDK 1.4 or greater. 
2, the compiler will not allow the use of the assert statement. 

sing the Eclipse IDE, you need only version 1.4 JRE or better installed 
elected as the compiler compliance level. To make sure that the 
compliance level is set correctly, do the following: 

1. Choose WindowOPreferences. 

The Preferences dialog box appears. 

2. On the left side of the screen, choose Java. Click the plus sign (+) next 
to Java to see the other options. 

3. Click Compiler. 

The Complier dialog box appears. 

4. Choose the Compliance and Classfiies tab. Make sure that the 
Compiler compliance level is set to 1.4 (see Figure 8-2). 
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Classfile Generation 

& Add variable attributes to generated class files (used by the debugger) 
^ Add line number attributes to generated class files (used by the debugger) 
Add source file name to generated class file (used by the debugger) 

P Preserve unused local variables (i.e. never read) 



Restore Defaults 




If you're using the command line to invoke the compiler, use the source 1.4 
command-line option to ensure that the compiler will accept assert 
statements. 
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The assert statements are interesting because you can turn them on and off 
at runtime. Assertions are turned off by default. To turn assertions on, use 

r-enableassertions command-line switch when starting the pro- 
example: 

Java -ea myProgram 

turns on (enables) assertion checking in myProgram. 

When developing and testing, assertions are valuable debugging tools for shak- 
ing out error conditions. But in production code, these conditions should no 
longer exist. If some doubt exists about whether to use an assertion or throw 
an exception, consider whether the condition could arise in a production 
state or not. If it could, throw the exception. 

To find out more about assertions and their use, look at the following Web site: 

java . sun . com/ jjf se/1 . 4. 1/docs/gui de/1 ang/ assert . html#i ntro 



Handling Exceptions \lourself 

You have two choices for exception handling in Struts: use declarative excep- 
tion handling (explained in the next section) or handle the exceptions yourself. 

In Struts, the Acti on classes are the most likely candidates for handling 
exceptions because they're generally the root class of other classes that you 
might have written for your application. Therefore, the Acti on class should 
probably catch all checked exceptions. 

The handling of all exceptions in the Acti on class should be pretty much the 
same: 

1. Save information about the exception. 

2. Recover from the error condition, if possible. 

3. If necessary, provide the user with a clear and concise message that 
explains what has happened and what the user should do (if anything) 
to correct the problem. 

4. When it is not possible to recover from the error, fail in a graceful way. 

These four steps are discussed in this section. 
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uoned, exceptions contain valuable information. The first step in han- 
Iceptions is to extract and save the information. What you extract will 
depend on the type of error you're handling. For example, the error is an 
SQLExcepti on, you might want to get the SQL string and save it. You can 
save the information by printing to the console through the use of System . 
out . printl n or excepti on . pri ntStackTrace (or both). The other possi- 
bility is to save the information to a log file. We discuss logging in Chapter 13. 



Recovering from errors 

When an error occurs, you have to determine whether or not you can recover 
from the condition and continue processing. The recovery is application spe- 
cific. Sometimes recovery may be as simple as reinitializing a variable and 
trying again. Other times, it may mean undoing a series of steps and then 
informing the users of the failure and asking them to try again. 



Inform the user 

To continue processing, the user may need to be notified of the situation. 
This notification might be by means of messages that appear on the normal 
presentation page that the user would normally receive. In particular, if the 
user has submitted unacceptable data, you should provide a message indicat- 
ing what needs to be corrected. 

Another possibility is to forward the user to a specialized presentation page 
that details more general errors. For example, the page could let the user 
know that the data just submitted could not be saved due to an error in the 
network and ask the user to try again. 



Fait gracefully 

If recovery from the exception is not possible, failure should occur as grace- 
fully as possible. Perhaps the situation affects the state of only one user. For 
example, data stored in the user's session may have become corrupted or 
suspect, and recovery of the data may not be practical. In that case, one 
choice is to log the user off the system and invalidate the user's session. In 
effect, this choice makes the user start over. 

More serious scenarios might mean accepting no further connections until 
the responsible party can assess the situation. 
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Declarative Exception Handling 

1 1^ I J ^) ^^JuQ^ers some help with exception handling through the exception declar- 
ative tags of the struts -confi g . xml file. In the "Global exceptions" section 
in Chapter 7, we explain that the <gl oba 1 - except ions> and <exception> 
tags in the struts-config.xml file are useful for exception handling. 



The execute method of the Acti on class can throw an exception of type 
Excepti on. Doing so allows exceptions to be handled by RequestProcessor, 
which determines whether the exception has been declared in the configura- 
tion file through the <exception> tag. If so, the exception handler class that 
was defined is called, org . apache .struts . acti on . Excepti onHandl er is 
used by default. However, you can also create your own subclass of Exception 
Handler — for details, see the "Extending the ExceptionHandler" section 

Excepti onHandl er is then responsible for preparing information to be for- 
warded to the presentation layer. Specifically, Excepti onHandl er gets or 
creates ActionError with the exception information and puts it into an 
Acti onErrors object. Excepti onHandl er then determines where to pass 
control by using Acti on Forward. Figure 8-3 shows this process graphically. 



Figure 8-3: 

The flow of 
declarative 
exception 
processing. 



RequestProcessor determines 
whether an exception handler is 
defined for this exception 
(meaning an exception tag was 
defined in struts-config.xml). If 
so, RequestProcessor calls the 
execute method, passing all 
information. Otherwise, it 
throws another exception. 



ExceptionHandler creates or gets 
ActionForward for this exception 
and creates and stores the 
appropriate ActionErrors. It then 
returns the ActionForward. 



ExceptionHandler 





Any Class 



Your Action doesn't handle 
the exception, so it's 
passed up the hierarchy 



Error.jsp displays error 
messages from 
ActionErrors. 



An error condition is 
encountered and a 
ModuleException is thrown. 
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Declaring the exception 



w the declaration is defined, let's first take a look at the <excep- 
'g. (See Chapter 7 for the complete definition of the <exception> 
tag's attributes.) The <exception> tag allows you to specify a particular 
exception type that will be handled by Struts. The <excepti on> tag has two 
required attributes: key and type. The key attribute defines the message 
resource key that will be put into the Act ion Error object for the exception. 
The type attribute refers to the fully qualified class name of the particular 
exception type to be handled. An example of an exception definition follows: 

<exception key =" error. db. general" 

ty pe= "com.othenos. purchasing. common. DBExcept ion" /> 

If the path attribute is not defined, Excepti onHandl er uses the i nput 
attribute of the acti on definition where the exception was thrown. 



Global or local exception handling 

Exceptions can be defined globally for the entire application or locally for a 
particular Acti on. In this respect, exceptions are similar to forwards. If you 
choose to define an exception globally and that exception type occurs in any 
Acti on in your application, it's handled in the manner defined in the global 
definition. One caveat: if the exception type is also defined locally for a par- 
ticular Acti on, the local definition takes precedence. 

To define an exception globally, simply place the exception definition in the 
<g 1 oba 1 - excepti ons> tags. For example, you could specify the preceding 
exception example as global in this manner: 

<global -excepti ons> 

<exception key =" error. db. general" 

ty pe="com.othenos.purchasing. DBExcept i on" /> 
</global -excepti ons> 

And you could also define the same exception in an Acti on definition to 
make it local to the Acti on, as shown here: 

<action path="/home" 

type=" com. othenos. purchasing. struts . HomeActi on" 
scope=" request" 
val i date="f al se" > 
<forward name="success" path="/index. jsp"/> 
<exception key =" error. db. my act ion" 

ty pe=" com. othenos. purchasing. DBExcept i on" /> 

</acti on> 
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If DBExcepti on occurs, Excepti onHandl er determines whether the excep- 
tion occurred in HomeActi on. If the exception occurred in HomeActi on , the 
.my acti on key is used to create ActionError. Otherwise, the 
.general key defined for the global exception is used. Of course, 
you can differentiate the two exceptions much further by using additional 
attributes, such as defining different Excepti onHandl ers or destination paths. 



Extending Exception Handler 

Struts provides a plain-vanilla Excepti onHandl er class that is useful as it is. 
However, if you're interested in additional capabilities, you need to extend 
the Excepti onHandl er class. Some of the more commonly desired features 
might be to 

I, Log error information before passing control to the presentation layer 
*<" Send an e-mail to one or more people responsible for the application 
Handle chained exceptions 

Your subclass of Excepti onHandl er needs to override the execute method 
and potentially the storeExcepti on method. The execute method is where 
you need to put your customized functionality, as shown in Listing 8-3. 

Listing 8-3 Extending the ExceptionHandler Class 

public class CustomExceptionHandler extends ExceptionHandler 
( 

Log log = LogFactory.getLogtCustomExceptionHandler. class); 
// commons logging reference 

* Handle the exception. Standard execute method with addition of 

* logging the stacktrace. 

*/ 

public Acti onForward execute( 
Exception ex, 
ExceptionConfig ae, 
Acti onMappi ng mapping, 
ActionForm formlnstance , 
HttpServletRequest request, 
HttpServl etResponse response) 
throws Servl etExcepti on 

( 

// write the exception information to the log file 

logExceptionChain(ex) ; 

// process the exception as normal 

return super. execute(ex, ae, mapping, formlnstance, request, response); 



(continued) 
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ogging exception stack trace, including chained exceptions 

* modified from version by Keld H. Hansen 

* http : //javaboutique .internet. com/tutor i al s/Chai ned_Excepti ons/ 

* @param thr 
*/ 

private void 1 ogExcepti onChai ntThrowabl e thr) 
( 

StackTraceElement[] s; 
Throwable t = thr; 

StringBuffer errorMsg = new StringBuffer("\nException chain (top to 

bottom) :\n") ; 
while (t != null ) 
( 

errorMsg. appendt " \n" ) ; 

s = t.getStackf racet ) ; 

StackTraceEl ement sO = s[0]; 

errorMsg. append( t . toStri ng( ) ) ; 

errorMsg. appendt " at " + sO . toStri ng ( ) + "\n"); 

if (t.getCause( ) == null ) 

( 

errorMsg. appendt" \n") ; 

errorMsg. appendt "Compl ete traceback (bottom to top):\n"); 

for tint i = 0; i < s. length; i++) 

errorMsg. appendt " at " + s[i ] .toStri ngt ) + "\n"); 

) 

t = t . getCauset ) ; 

1 

log. error (errorMsg. toStn'ngO) ; 



To let Struts know about the new CustomExcepti onHandl er, you need to 
add it to one or more of the <excepti on> tag definitions. In our previous 
example, you would just need to add the handler attribute with the fully 
qualified class name of the custom handler, as shown here (taken from the 
example application in Chapter 14): 

<excepti on 
key=" " 

path=" /error . jsp" 

hand! er="dummi es. struts. music. CustomExcepti onHandl er" 
type="org . apache . struts . uti 1 .Modul eExcepti on" /> 

Now whenever Modul eExcepti on occurs, CustomExcepti onHandl er 
processes the exception. Note that the key defined forModuleExeception is 
empty. This is because the message key is placed in Modul eExcepti on when 
it is created. We do not omit the key attribute because it is required. 
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If you want all exceptions to be handled by CustomExcepti onHandl er, just 
change the ty pe attribute to the root class of all exceptions, j a v a . 1 a n g . 

DropBodkS' 6 

Handling RuntimeExceptions in Struts 

RuntimeExcepti ons and its descendents are unchecked exceptions. There- 
fore, you don't have try /catch blocks that try to trap and recover from the 
exceptions. However, it's bad form to let the exception propagate back to the 
user so that the user sees the raw stack trace information in the browser. 

You can use the declarative exception mechanism to catch Runtime 
Excepti ons and display a more reasonable page when exceptions occur. The 
first step is to create the global exception definition for Runti meExcepti on 
in the struts-config.xml file, as shown here (the example is from the 
MusicCollection application in Chapter 14): 

<global -excepti ons> 

<exception bundl e= "Appli cat i on Re sources" 
key="error . Runti meExcepti on" 
path="/baderror.jsp" 

handl er="dummi es. struts. music. Custom Excepti onHandl er" 
type=" Java . 1 ang . Runti meExcepti on" /> 
</global -excepti ons> 

The error . RuntimeExcepti on key is used to retrieve the error message to 
display on the presentation page. The path attribute specifies the path to 
baderror . j sp to display if the Runti meExcepti on occurs. 

The second step is to define the JSP page that will display the error message 
to the user. Listing 8-4 is an example of the content of such a page. (The entire 
page is defined in Chapter 14.) 



Listing 8-4 Snippets from the baderror.jsp Page 



1 


<%% include fi le="tagl ibs.jsp" %> 




2 


<fmt : setBundl e basename="ApplicationResources" /> 




3 


<table> 




4 


<tr> 




5 


<td al i gn="center" col span="2" style="font-fami ly: 'MS 


Reference Sans 




Serif, 'Verdana Ref , sans-serif ;font-size: 


18px;color:red;"> 


6 


<fmt: mess age key=" error. RuntimeExcepti on" /> 




7 


</td> 




8 


</tr> 




9 


<tr> 




1( 


) <td width="55" align="left"> 





(continued) 
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img src="images/annoy.gif" name="annoy" width="54" height="54" 
border="0"> 

9 

13 <td> 

14 <html : 1 ink pa ge= " / 1 ogoff .do"> 

15 <fmt:message key="goto. logoff"/) 

16 </html:link> 

17 </td> 

18</tr> 
19</table> 

Figure 8-4 shows the baderror.jsp page as it would appear to the user. 
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The key parts of the JSP snippet are lines 6 and 14-16: 

Line 6: Defines the error message to be displayed to the user. 

f Lines 14-16: Define a link that the user can click to log off the applica- 
tion. In practice, you may have already logged the user off the system. 
Programmatically logging the user off the system would be easy to do if 
you were using a customized version of the Except ionHandler class. 



Chapter 9 

Friendly with Plug-ins 



In This Chapter 

Understanding the Plugln interface 
Creating and configuring a plug-in 
Using the Validator plug-in 



J\ n application often needs to initialize certain resources when starting 
v \ up and release resources when shutting down. If you're writing a stan- 
dard application, initializing and releasing resources are not much of an issue 
because you have complete control over the code that's responsible for 
startup and shutdown. However, these functions are not as simple with a 
Struts Web application because ActionServlet gets startup and shutdown 
notifications from the Web container. 

You could extend ActionServletto add custom startup and shutdown 
actions, but that's messy — the number of actions could be large and unre- 
lated. Fortunately, the Struts developers have anticipated the need to control 
startup and shutdown by including a plug-in architecture with the Struts 
framework. In this chapter, we explain how to use and implement plug-ins. 



Usinq the Ptugh Interface 

If you need custom startup or shutdown actions, you can simply create your 
own plug-in class by implementing the org. apache. struts. act ion. Plugln 
interface rather than extend theActionServlet. The Plugln interface speci- 
fies two methods that you need to define: destroy and i n i t. The interface is 
shown in Listing 9-1. 
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Listing 9-1 Plugln Interface 
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blic interface Plugln 



1 ic void destroy( ) ; 
public void i ni t ( Acti onServl et servlet, 
Modul eConf i g config) 
throws Servl etExcepti on ; 



At startup, the ActionServlet checks to see whether any plug-in classes 
need to be called. If there are any plug-in classes, the 1 n i t method of each 
plug-in is called. Similarly, when the Web container notifies the ActionServlet 
of an impending shutdown, the Acti onServl et calls the destroy method of 
all plug-in classes in its list. 



Implementing and Configuring 
\lour OvOn Ptug-in 

You can create your own plug-in simply by implementing the destroy and 
i ni t methods of the Plugln interface. Listing 9-2 shows an example of how to 
implement a plug-in for the MusicCollection Web application in Chapter 14. 
Don't worry if you don't understand what's happening in the two methods, 
because they're specific to this particular application. What is important to 
know is that i ni t is called at startup and destroy is called at shutdown. 



Listing 9-2 Plug-in for a Purchase Order Web Application 

1 public class StartupManager implements Plugln 
( 

2 Log log = LogFactory. getLog(StartupManager. class) ; 

3 Servl etContext sc; // reference to servlet context for destroyO 

/** 

* initializes resources at application startup 

* @param argO 

* @param argl 

* ©throws Servl etExcepti on 
*/ 

4 public void i ni t ( Act i onServl et argO, ModuleConfig argl) 

5 throws Servl etExcepti on 
( 

// save the servlet context for shutdown needs 

6 sc = argO.getServletContextt ) ; 

// define the lists and place in the application context 

// set up the years 
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1 og. i nfo( " Ini ti al i zi ng years .") ; 

ArrayList years = new ArrayListO; 

int year = Calendar. getlnstance( ) . get ( Ca 1 enda r . YEAR) ; 

ford nt i-0; i < 50; 



11 years .add (String. val ueOf (year- i ) ) ; 
) 

12 sc.setAttribute( "years" .years ) ; 



// set up the album types 

// better solution would be to retrieve these values from a database. 

13 log.infoC'Initializing types."); 

14 ArrayList types = new ArrayListO; 

15 types. addC'CD"); 

16 types. addC'LP"); 

17 types. add( "MP3" ) ; 

18 types . add ( "Tape" ) ; 

19 sc.setAttri bute( "types" .types ) ; 



// set up the album catagories 

20 log.infoC'Initializing categories."); 

21 ArrayList categories = new ArrayListO; 

22 categories. add ("Classical"); 

23 categori es . add ( "Country" ) ; 

24 categories. addCEasy Listening"); 

25 categories. addCHeavy Metal"); 

26 categori es . add ( "Jazz" ) ; 

27 categori es . add ( "New Age" ) ; 

28 categori es . add ( "Pop/Rock" ) ; 

29 categories. addC'R & B"); 

30 categori es . add ( "World" ) ; 

31 sc.setAttri bute( "categori es" .categori es ) ; 



1 



* releases resources at application shutdown 
*/ 

32 publ i c void destroy( ) 
( 

// shut down the dbcp 

33 1 og . i nfo( "Shutti ng down the DataSource connection pool."); 

34 DataSource dbConnMgr = (DataSource)sc.getAttribute("musiccollection"); 

35 dbConnMgr = null; 

36 sc . removeAttri bute( "musi ccol lection" ) ; 



// final message 
37 log.infoOMusic.com has shutdown."); 



You need to be aware of a couple of things when implementing a plug-in. The 
i ni t method can take two parameters: a reference toActionServlet and 
Modul eConf i g. You can use Acti onServl et to get any resources that it 
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might help you control or get information for your initialization process. In 
line 6, we use Acti onServl et to get a reference to Servl etContent, which 
>lication scope, to get and set resources in that scope. We also save 
nee to Servl etContext to make use of it in the destroy method. 

The ModuleConfig parameter can contain a reference to the module currently 
being initialized. Referencing the module is useful if your Web application has 
multiple modules, because you may want to perform different initialization 
actions depending on the module. If you are using only the default module, 
you can safely ignore this parameter. 

The destroy method takes no parameters. If destroy needs a resource that 
you gathered in the i ni t method, be sure to save the resource as an instance 
variable. In lines 34-36, the destroy method accesses Servl etContent to ref- 
erence DataSource and gracefully shut it down. 

After you create a plug-in, the next step is to notify Struts that the plug-in is 
ready for use, which you do in the struts-config.xml file. Configuring plug- 
ins in struts -conf i g . xml is simple and straightforward. In the "Plug-in 
Configuration" section of Chapter 7, we describe the use of the <pl ug-i n> 
tag in the configuration file. This simple tag has only one required attribute, 
className. You must specify the fully qualified class name of the plug-in that 
you want to use. 

The only other tag that you may include in the < p 1 u g - i n > tag is the < s e t - 
property) tag. Use this tag to pass initialization parameters to the plug-in, if 
needed. Here is an example of configuring the plug-in described in Listing 9-1: 

<pl ug-i n cl assName="dummi es. struts. music.StartupManager" /> 

Be sure to remember that the sequence of elements in the strutsconfig. 
xml file is important. The plug-in element is the last element defined. 



Working itiith the Validator PiuqAn 

The Validator plug-in comes with the Struts framework. You use this plug-in 
to validate form data in a declarative manner instead of using the standard 
va 1 i date method in Acti on Form. (See Chapter 6 for information on using 
the val i date method.) 

The Validator plug-in has the following advantages over using the val i date 
method: 

I You can add, modify, or remove validation rules for form fields without 
changing the source code. 

One text file centrally contains validation rules for all form fields. 
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V The plug-in provides many common validation rules. 
You can use the plug-in with DynaActi on Forms. 
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Configuring the Validator plug-in 



The Validator requires two xml configuration files: va 1 i dati on . xml and 
validator-rules. xml. You might think that the val i dati on . xml file is 
more interesting because that is where you define the forms and fields to vali- 
date as well as the rules to use when validating those fields. The actual rules 
that perform the validation are defined in validator-rules. xml. 

The val i dati on . xml and validator-rules, xml files share the same DTD. 
(For details on DTD, see "Editing the Web Container Configuration File" in 
Chapter 7.) In practice, however, each .xml file uses a different subset of the 
DTD syntax. 

The Validator configuration files have a DTD file that defines the grammar 
acceptable in the configuration. Each file should begin with a DOCTYPE indi- 
cating the version of the DTD that you're using. The following example speci- 
fies version 1.0.1 of the Validator DTD: 

<! DOCTYPE form-validation PUBLIC 

"-//Apache Software Foundati on//DTD Commons Validator Rules Configuration 
1.0.1//EN" 

"http: //Jakarta. apache . or g/ commons /dtds / val idator_l_0_l . d t d " > 

The root tag — and therefore the first tag — in Validator configuration files is 

<f orm- val i dati on>. The DTD syntax for the <f orm- val i dati on> tag follows: 

< ! ELEMENT f orm- va 1 i da ti on (global*, formset*)> 
We show examples of using the DTD throughout this section. 



Usinq the Validator pluq-in 

To use the Validator plug-in, you need to do the following: 

1. Create your form class by extending org. apache, struts . val i dator . 
Val i datorActi onForm instead of the normal org . apache . struts . 

a ct i on. Act i on Form. 

2. Configure the Validator plug-in in the struts confi g .xml file. 

3. Define the validation rules to apply to your form fields by configuring 
the val i dati on .xml file. 

4. Tweak the struts config.xml file and message resources. 
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We explain each of these steps in detail by modifying the Login example from 
Chapter 3. 

DBooks 

Extending the ValidatorForm class 

Rather than creating Log i n Form by extending the Ac ti on Form class, you 
should extend the Val i da tor Form class. What does this accomplish? 
Essentially, you'd have a prebuilt validate method that takes advantage of 
the validation rules that you defined in the va 1 i dati on . xml file. Therefore, 
you would not need a validate method in Logi n Form. Listing 9-3 shows how 
Log in Form should look when you extend the ValidatorForm class. 



Listing 9-3 LoginForm for Use with the Validator Plug-in 




public class LoginForm extends ValidatorForm 




( 

private String userName; 
private String password; 




public void reset(Acti onMappi ng mapping, HttpServl etRequest request) 
< 


password = " " ; 
userName = " " ; 

1 




public String getPasswordt ) ( 
return password; 

1 




public String getUserNamet ) ( 
return userName; 

) 




public void setPassword(String string) ( 
password = string; 

1 


public void setUserName(String string) 1 
userName = string; 

1 

1 



Compare this code to Listing 3-4 in Chapter 3. Notice the lack of a va 1 i date 
method. This method is no longer needed because the Val i datorForm we 
are extending already has one. The validate method in the Val i datorForm 
class knows how to perform validation based on the v a 1 i d a t i o n . xm 1 and 
validatorrules.xml files. These files are described in the next section. 
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Configuring the Validator plug-in 

DropBocyk& ? con fa f ite 

The next step in setting up the Validator plug-in is to configure the plug-in in 
the struts-config.xml file. The configuration is just like the previous plug- 
in definition (see the "Configuring Plug-ins" section) with one addition — you 
need to add one parameter to pass to the plug-in. The Validator needs to 
know the context-relative paths so it can find the va 1 i dati on . xml and 
validator-rules. xml configuration files. You typically place these files in 
the WEB - 1 N F folder. Here is the configuration information that you would add 
to the struts-conf i g . xml file in the Login project example: 

<!-- ========== Plug-in Definitions 

=========================== > 

<pl ug-i n 

className= "org. apache. struts. validator.ValidatorPlugIn"> 
<set- property proper ty=" pathnames" 

val ue=" /WEB-INF/validator-rules.xml , 
/WEB- INF/val idation.xml "/> 

</pl ug-i n> 



Defining the fields to Validate 

The original Login project example (in Chapter 3) did not use the Validation 
plug-in and therefore did not include the Validation configuration files, 
va 1 i dati on . xml and validator-rules, xml. However, when you use the 
Validator plug-in, you must place the two configuration files in the WEB - 1 N F 
folder because that is the location that the plug-in configuration specifies. 

The third step for using the Validator is to define the forms, fields, and rules 
to apply to the fields in the val i dati on . xml file. To find out how to do this, 
note the DTD for the configuration files: 

< ! ELEMENT f orm- va 1 i dati on (global*, formset*)> 

The form- val i dati on element is the root element for both of the configura- 
tion files; it can contain one or more global elements and one or more 
f ormset elements. We discuss the f ormset element here and cover the 
global element later in this chapter, in the "Looking more closely at valida- 
tion.xml" section. 



The syntax for defining f ormset follows: 



< ! ELEMENT 


f ormset 


(constant* , 


f orm+)> 


< ! ATTLIST 


f ormset 


1 anguage 


CDATA ^IMPLIED 






country 


CDATA //IMPLIED 






variant 


CDATA ^IMPLIED > 
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The f ormset element defines at least one or more forms to be validated for a 
particular Loca 1 e. If you don't use any of the attributes, f ormset represents 
It Loca 1 e. Otherwise, you can specify different formsets for a dif- 
t^^ca 1 e language, country, variant, or any combination. The f ormset 
element can also contain constant definitions, which we explain in the 
Looking more closely at validation.xml" section. 



The syntax used to define a form follows: 
< ! ELEMENT form (field+ )> 

< ! ATTLIST form name CDATA #REQUIRED> 



The form element is used to define the fields of a form to be validated. The 
name attribute is required and corresponds to the name of the form as 
defined in the struts confi g . xml file. 



Afield is defined using the following syntax: 

< ! ELEMENT field (msg | argO | argl | arg2 | arg3 | var)*> 
<! ATTLIST field property CDATA ^REQUIRED 
depends CDATA ^IMPLIED 
page CDATA ^IMPLIED 
indexedListProperty CDATA ^IMPLIED > 



The field element defines the properties to be validated. In a Web applica- 
tion, a field could also correspond to a control on an HTML form. To validate 
the properties, the Validator works through a JavaBean representation, the 
specified Acti onForm. The f i el d element can accept up to four attributes: 

i>* property: The property in the JavaBean corresponding to this f i el d 
element. This attribute is required. 

depends: The comma-delimited list of validators to apply against this 
field. For the field to succeed, all validators must succeed. Validators 
represent the rules against which the value of the field will be tested. 

V page: The JavaBean corresponding to this form may include a page 
property. Only fields with a page attribute value that is equal to or less 
than the page property on the formbean are processed. This attribute is 
useful when using a wizard approach to completing a large form, to 
ensure that a page is not skipped. The default value is 0. 

indexedListProperty: The method name that returns an array or a 
Collection that retrieves the list of indexed properties and then loops 
through the list performing the validations for this field. 



The msg element is defined using this syntax: 



< ! ELEMENT 


msg 


EMPTY) 






<! ATTLIST 


msg 


name 


CDATA 


^IMPLIED 






key 


CDATA 


^IMPLIED 






resource 


CDATA 


^IMPLIED > 
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The msg element defines a custom message key to use when one of the val- 
idators for this field fails. Each validator has a default message property 
ye explain in the next section) that is used when a corresponding 
>is not specified. Each validator applied to a field may have its own 
"msg element. The msg element accepts up to three attributes: 



V name: The name of the validator corresponding to this msg. 

key: The key that returns the message template from a resource bundle. 

V resource: Determines whether the key is a literal value or a message 
resource bundle key. If you set this attribute to false, the key is a literal 
value rather than a message resource bundle key. The default value is 

true. 



You can specify up to four args for a field. The following is the syntax to 
define each of them: 



< ! ELEMENT argO-3 EMPTY> 

< ! ATTLIST argO-3 name CDATA ^IMPLIED 

key CDATA ^IMPLIED 

resource CDATA ^IMPLIED > 



The argO-3 (argO, argl, arg2, arg3) elements define the first through 
fourth replacement value to use with the message template for this validator 
or this field. Each of the argO-3 elements accepts up to three attributes: 

f" name: The name of the validator corresponding to this msg. 

key: The key that will return the message template from a resource 
bundle. 

i>* resource: Determines whether the key is a literal value or a bundle key. 
If you set this attribute to f a 1 se, the key is a literal value rather than a 
bundle key. The default is true. 

The last element that can be included in a field definition is va r. The follow- 
ing is the syntax for defining it: 

<!ELEMENT var (var-name, var-value)> 



The var element can set parameters that a field may need to pass to one of 
its validators, such as the minimum and maximum values in a range valida- 
tion. These parameters may also be referenced by one of the a rgO -3 elements 
using a shell syntax: ${var:var-name). 

The var-name element is the name of the var parameter to provide to a field's 
validators. This element has the following syntax: 

< ! ELEMENT var-name (#PCDATA)> 
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i\ regular expression is a concise way to 
describe and search for complex string pat- 
terns. The term originated in the UNIX environ- 
ment, but regular expressions are now available 
in many languages, including Java. Fortunately, 
regardless of the language, you use the same 
syntax to create a regular expression. If you've 
never used regular expressions, we suggest 
that you take some time to find out about them. 
The following Web sites offer tutorials: 

www .regular-expressions.info/ 

tutori al . html 
Java. sun. com /docs/books/ 

tutori al/extra/regex 



Regular expressions 



History buffs might be interested in knowing 
that the origins of regular expressions came 
from physiology and mathematics, not computer 
science. According to Jeffrey E. F. Friedl, in the 
forties Warren McCulluch and Walter Pitts cre- 
ated neuron-level models of how the nervous 
system operated. Mathematician Stephen 
Kleene later described these models using 
mathematical notation that he called regular 
expressions. Ken Thompson incorporated that 
system of notation into qed (the grandfather of 
the UNIX ed). Since then, regular expressions 
have appeared in UNIX and UNIX-like utilities. 



The var-value element is the value of the v a r parameter to provide to a 
field's validators. This element has the following syntax: 



< ! ELEMENT var-va 


lue (#PCDATA)> 






Now that you know the grammar 


1 


or the va 1 " 


dation.xml file, it's time to 



look at its sister file, validator-rule. xml. 

The validator-rules. xml file has a number of predefined validators that 
you can use in the validation, xml file to perform various checks on the 
value of specified fields. The following is a current list of each of the valida- 
tors and their function. Note that va r refers to the va r element defined in the 
field element. You can get the validator-rules. xml file from the Struts 
distribution 1 i b directory. 

f required: Checks that the field isn't null and that length of the field is 
greater than zero, not including white space. 

f"validWhen: Checks to see that certain conditions exist for the field to be 
validated. You must specify var as test with the value consisting of an 
expression that evaluates to a boolean value. The expression must eval- 
uate to true for the validation to succeed. 

Vminlength: Checks whether the field's length is greater than or equal to 
the minimum value. Specify varasminlength with the minimum value 
allowed. The value should be an integer. 

j^maxlength: Checks whether the field's length is less than or equal to the 
maximum value. Specify varasmaxlength with the maximum value 
allowed. The value should be an integer. 
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V mas k: Checks whether the field matches the regular expression in the 



mask attribute of the field. Specify the var as mask as a regular expres- 
For more information on regular expressions, see the "Regular 
essions" sidebar. 

byte: Checks whether the field can safely be converted to a byte 
primitive. 

short: Checks whether the field can safely be converted to a short 
primitive. 

i nteger: Checks whether the field can safely be converted to an integer 
primitive. 

long: Checks whether the field can safely be converted to a long 
primitive. 

float: Checks whether the field can safely be converted to a float 
primitive. 

double: Checks whether the field can safely be converted to a double 
primitive. 

f" date: Checks whether the field is a valid date. 

i>* i ntRange: Checks whether a field's value is within a range. Specify vars 
as mi n and max with the beginning and ending values allowed. The 
values should be integers. 

f 1 oatRange: Checks whether a field's value is within a range. Specify 
vars as mi n and max with the beginning and ending values allowed. The 
values should be of the type f 1 oat. 

creditCard: Checks whether the field is a valid credit card number. 
Confirms a credit card number as a valid American Express, Visa, Master 
Card, or Discover credit card. 

ema i 1 : Checks whether a field has a valid e-mail address. 

Now that you know about va 1 i dators and the syntax of the va 1 i dati on . 
xml file, you can create your own va 1 i dati on . xml to validate Logi nForm. 
The Logi nForm example has two fields to validate: userName and password. 
Listing 9-4 shows the entire val i dati on . xml file. 



Listing 9-4 validation.xml File for the Login Application 

<?xml vers i on=" 1.0" encodi ng=" ISO-8859-1 " ?> 
<! DOCTYPE form-validation PUBLIC 

"-//Apache Software Foundati on//DTD Commons Validator Rules Configuration 

1.0.1//EN" 

"http: //Jakarta .apache . or g/ commons /dtds/ val idator_l_0_l . dtd " > 

1 <form-validation> 

2 <!-- ========== Form Definitions ===================== --> 

3 <formset> 



(continued) 
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9 

10 
11 
12 

13 
14 
15 
16 
17 



<form name="l oginForm") 

<field property="userName" 
depends="requi red") 
<arg0 key=" error . user name . requi red"/> 

</field> 



<field property="password" 

depends=" requi red , mi nl ength " > 
<arg0 key=" err or. pas sword, requi red' 
<argl key="${var:minlength)" name=' 

resource="false"/> 
<var> 

<var-name>mi nl ength</var-name> 
<var-value)5</var-value) 
</var> 
</field> 



/> 

mini ength" 



18 <field property="password" 

19 depends="maxl ength") 

20 <arg0 key="error. password. required"/) 

21 <argl key="${var:maxlength|" name="maxl ength" 
resource="false"/) 

22 <var) 

23 <var-name)maxl ength</var-name) 

24 <var-val ue)8</var-val ue) 

25 </var) 

26 </field> 

27 </form> 



28 </formset) 
29</form-val idation) 



Note the following lines in Listing 9-4: 



Line 4: You must define each form that the Validator needs to validate with 
a <f orm> tag. This line specifies that the 1 ogi nForm is to be validated. 

Lines 5-8: You need to define each field in the form that needs validating 
with a <f i el d> tag. These lines accomplish this definition for the 
userName field. 

V Line 6: The userName field is defined as a required field, nothing more. 
The depends attribute on this line is equal to required, the name of the 
rule to invoke when validating the field. The requi red validator checks 
to make sure that the value of the field is neither null nor an empty string. 

**" Line 7: Specifies argument one to be passed to the default message 
resource. The default message resource is 

errors . requi red={ 0 ) is required. 

Therefore, the argO value functions as a key to look up a message in the 
default message resource bundle. Instead of { 0 ) , the user sees that mes- 
sage in the default error message. 
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v 0 Line 9: Defines the password field i as the next field to validate. This 
field has two validators, requi red and mi nl ength. Both tests have to 
before the field is validated. The requi red validator does the same 
tion as for the previous username field. The mini ength validator 
checks to make sure that the length of the string is greater than or equal 
to some minimum length. The minimum length is specified with a <var> 
tag. va rname has tobeminlength. varvalue must be an integer value 
indicating the minimum length to check against. The default error mes- 
sage for mi nl ength is 

errors .mi nl ength = { 0 ) can not be less than {1) characters. 

Lines 11 and 12: The default message takes two parameters, a field name 
and a minimum length. These lines define these two parameters. The 
interesting point here is the dual use of the argO value. Because the code 
specifies two validators, the a rg values must apply to them both. As luck 
would have it, a rgO can fit for the default error message for either the 
requi red validator or the mi nl ength validator. 

i>* Lines 13-16: Define the minimum length of the password to be 5 
characters. 

Lines 18-26: Define the maximum length of the password field to be 8 
characters. We defined the password field twice because we also wanted 
to use the maxl ength validator. However, the default messages for 
mi nl ength and maxl ength both specify { 1 ) as the length value. The 
dilemma is that a rgl can take only one value. To get around this thorny 
problem, we chose to define the password field twice. The second time 
we applied only the maxl ength validator and gave the maximum allowed 
value for the a rgl value. 



The va 1 i dati on . xml file is now complete and ready to use with the updated 
Login application. 



Tuteaking other files 

You must check a couple of other files to make sure that they're ready for 
the Validator. The acti on definition in the struts confi g . xml file that's 
using the form to be validated must not have the validate attribute set to 
false (true is the default value) . Otherwise, the validate method of the 
Va 1 i dateActi on superclass will not get called. 

In the message resources file, you need to include the error message defini- 
tions that the Validator uses. The Appli cat i on Re sources file used for the 
Login project in Chapter 3 did not have these messages. You can find the list 
of error messages at the beginning of the validator-rules. xml file. The 
error messages are as follows: 
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# Struts Validator Error Messages 
errors . requi red= 1 0 ) is required. 

e|^o£%.minlength={0) can not be less than 11) characters. 
ejr\oQ.maxlength=|0) can not be greater than {1} characters, 
errors . i nval id={ 0) is invalid. 

errors . byte= { 0 ) must be a byte, 
errors . short = { 0 ) must be a short, 
errors . i nteger={ 0 ) must be an integer, 
errors . 1 ong= { 0 ) must be a long, 
errors . fl oat={ 0 ) must be a float, 
errors . doubl e={ 0 ) must be a double. 

errors . date={ 0 ) is not a date. 

errors . range={ 0 ) is not in the range {1} through 12). 
errors . credi tcard= { 0 ) is not a valid credit card number, 
errors . emai 1 ={ 0 ) is an invalid e-mail address. 

You need to add these messages to the Appli cat ion Re sources file. 



DropBoo 



Try out the modified Login application 

To try out the modified Login application, replace the three original files in 
your IDE with the newly modified ones: LoginForm, struts-config.xml, 
and Appl i cati onResources . properti es. Then add the two validation 
configuration files, va 1 i dati on . xml and validator-rules. xml, to the 
WEB - IN F folder. Copy the entire Logi n folder to the webapps folder of 
Tomcat, replacing the existing Logi n folder (if it exists). 

When you run the application, you can test that the new validation is working 
by entering any username and then a password of less than five characters. 
You should see an error message indicating that the password field cannot 
be less than five characters, as shown in Figure 9-1. This shows that the 
mi nl ength validator caught the error. 



Looking more closely at Validation. xml 

We skipped over some of the important features of configuring the validation, 
xml file to keep the Login example as simple as possible. In this section, we 
cover all the additional parts of the grammar we missed earlier. 

You can use the constant element in either the f ormset element or the 
gl obal element. The grammar is as follows: 

<!ELEMENT constant (constant-name, constant-val ue )> 
< ! ELEMENT constant-name (#PCDATA)> 
< ! ELEMENT constant- val ue (#PCDATA)> 
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The constant element defines a static value that you can use as replacement 
parameters in f i el d elements. The constant-name and constant-value ele- 
ments define the constant's reference ID and replacement value, respectively. 

An example might help clarify the use of constant. Suppose you want to vali- 
date a telephone field using the mask validator. The mask validator takes a reg- 
ular expression and applies it to the field to be validated. Here is an example of 
verifying that the phone field has the form nnn-nnn-nnnn, where n is a digit: 

<field property="vendorPhone" 

depends="requi red, mask") 
<argO key=" vendor . phone. label"/) 

<var> 

<var-name>mask</var-name> 
<var-val ue> A \d{ 3 ) -\d ( 3 ) -\d (4 ) $</var- val ue> 
</var> 
</field> 

Rather than using the regular expression in the varvalue tag, you could 
define a constant with that value and then reference the constant in the var- 
value tag. Listing 9-5 shows an example of using the constant element. 



Listing 9-5 Example Using the constant Element 



1 


<constant> 




2 


<constant- 


name>phone</constant-name> 


3 


<constant- 


value> A \d(3)-\d{3)-\d{4)$</constant-value> 


4 


</constant> 





(continued) 
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<f iel d property="vendorPhone" 

depends = "requi red, mask "> 
<argO key="vendor.phone.label"/> 

<var> 

9 <var-name>mask</var-name> 

10 <var-value>${phone)</var-value> 

11 </var> 

12 </field> 



Lines 1-4 define the constant with a reference ID of phone, and the constant's 
value is the regular expression that you want phone numbers to conform to. 
Now when defining the value for the mask var, you can simply reference the 
phone constant instead of entering the regular expression itself, as shown in 
Line 10. 

The use of constants is valuable when you need to use the same value many 
times. For example, you may have many phone numbers to validate, such as 
mainPhone, nightPhone, personal Phone, faxPhone, cellularPhone, and 
alternatePhone.All would be expected to be the same format; therefore the 
phone constant could be used as shown in Line 10. Then, if the format 
changed (such as changing the dash to a blank between the area code and 
the remaining numbers), all you'd need to do is change the regular expres- 
sion in the phone constant. 

Now that you know how to use the constant element, where can you use it? 
There are two acceptable places: the f ormset element and the global ele- 
ment. Here is the grammar for both the f ormset and gl oba 1 elements: 

< ! ELEMENT f orm- va 1 i dati on (global*, formset*)> 
< ! ELEMENT global (validator*, constant*)> 
< ! ELEMENT formset (constant*, form+)> 

If you use constant in the formset element, all fields defined in that 
formset can reference it. To make it available in all f ormsets, define 
constant in the gl oba 1 element. 



Usitity the Validator With DynaAction Forms 

If you're using DynaActi on Forms instead of Act ion Forms, you can still use 
the Validator. However, you need to make the following changes: 

1. When you define DynaActi on Form in the strutsconf ig.xml file, 
the type attribute should be org . apache, struts . val i dator . 
DynaVal i da tor Form instead of the standard org. apache. struts, 
action. DynaActi onForm. 

2. Make sure that the form fields referenced in the validation, xml file 
match the form property names defined for the form in question. 
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In This Chapter 

Finding out how to use tag libraries 
Understanding Expression language 
Working with the Struts-EL tag library 
Using the JSTL tag library 
Discovering other Struts tag libraries 
Creating user interfaces with Java Server Faces 



■ M yhen creating JavaServer Pages, one of the prime considerations is to 
▼ ▼ eliminate or at least minimize the use of scriptlets in the pages. When 
scriptlets clutter up the page with Java code, making sense of the page is 
much more difficult. In addition, in larger projects, JSP pages belong more 
to the realm of user-interface designers and graphic artists. The use of Java 
logic in your pages mixes programming and design — a definite no-no. 

Custom tags were invented to alleviate this problem. They encapsulate higher 
level functionality in the form of a JSP tag. Usually a tag library consists of a 
family of tags that are all related to one area, such as formatting or using 
JavaBeans. 

The following two components make up the JSP Tag library architecture: 

*** Tag support classes: These Java classes are responsible for implement- 
ing the functionality of the tags in the library. Essentially, these classes 
represent the functionality of the scriptlet but don't need to appear 
themselves in the JSP page. Tag support classes are generally packaged 
in a JAR file. 



Tag Library Descriptor (TLD) XML file: An XML file describes all the tags 
that go to make up the tag library — names, attributes, and support 
classes. The JSP engine uses this file to determine how to process the tags. 
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to follow several generic steps to take to make use of any tag 
library. These steps are as follows: 

1. Move the TLD file for the library into the WEB INF folder. 

You could place the TLD file into any folder in the Web application's 
folder. However, most users place it in the W E B - 1 N F folder. 

2. Move the library's JAR file into the W E B I N F/ 1 i b folder. 

3. Define the tag library in the web . xml file. 

To define the tag library, use the JSP directive tag: 



<taglib> 

<taglib-uri>could be any distinct text</tagl ib-uri> 
<taglib-location>content relative path to the TLD</taglib- 
</taglib> 


location) 


As with all web .xml tags, the <tagl i b> tag is position dependent. Here 
is an example that defines the JSTL Core library: 


<taglib> 

<tagl ib-uri >jstl -c</tagl ib-uri> 
<taglib-location>/WEB-INF/c.tld</tag 

</taglib> 


lib-location) 




The URI to reference the Core library is j st 1 - c. You could have just as 
easily used bugaboo. However, it is good practice to keep the URI rele- 
vant to the library's name. The content-relative path to the TLD is /WEB- 
I N F / c . 1 1 d . Whenever you want to reference the library in the JSP file, 



you use the URI, as explained in the next step. 

Reference the TLD of the tag library in each JSP page that uses the 
library's tags. 

To reference the TLD, use the following JSP directive tag: 

<%@ taglib prefix="some prefix" uri="uri defined in the web. xml file" %> 
Here's an example of referencing the JSTL Core library defined in Step 2: 

<%@ taglib prefix="c" uri="jstl-c" %> 

Use the prefix when you use a particular tag from the tag library. For 
example, the JSTL Core library has a set tag. When using that tag, you 
must add the prefix you have defined for this library. In this case, you 
would use c, as in: 



<c:set 



\> 
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A common practice is to place all tag! i b directives in a single JSP file 
and i ncl ude this file in the other JSP pages. In this way, you have only 
unfile to edit when you want to add or remove additional tag library 
^rences. 

5. Add the desired tags to the JSP page. 

You can now successfully use the tags defined in the tag library. 



Expressing With the Expression Language 

The developers of Struts have recommended that you no longer use the stan- 
dard Struts tag library, which was based on the older runtime expressions to 
evaluate attribute values of tags. Instead, they have created a new library 
called Struts-EL which uses expression language (EL) for evaluating attribute 
values. Struts-EL uses the expression evaluation engine provided by the JSP 
Standard Tag Library (JSTL) 1.0. 

Runtime expressions are of the form <%= express ion %>. The expression 
represents some Java language expression. This is the standard way of evalu- 
ating expressions in JSP 1.2 and below. Beginning with JSP 2.0, the EL syntax 
is the preferred expression language because the EL syntax is simpler to 
learn than Java syntax. EL provides the users of the libraries a more flexible, 
intuitive, and powerful way to create expressions. 

The basic form for an EL expression is 

<some tag val ue= '$ I expression } ' \> 

Here is an example of an EL expression. This tag outputs the value of the 
user Name attribute that is stored in the session scope: 

<c:out val ue= ' $ { sessi onScope . userName ) ' /> 

EL evaluates and coerces the expression into the type expected by the value 
attribute. You can use either single or double quotation marks to delimit the 
EL expression. 

You can also intersperse text with expressions when the resulting type that 
the attribute expects is text: 

<a tag val ue= '${ expressionl ) any text $ {express i on2] more 
text' \> 

Here is an example of the preceding syntax. Assume the now variable con- 
tains the current date and time: 




<c:out val ue=' ${ sessi onScope . userName ) logged on at ${now)' /> 
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This example results in the String result of expressi onl concatenated with 
any text concatenated with the String result of express ionZ concatenated 



Expressions can contain any of the following items: 

V Identifiers 
v 0 Literals 

Operators 
v 0 Implicit objects 

These items are discussed in the next few sections. 



If a named variable exists in one of the four scopes (page, request, session, or 
application), the EL expression can retrieve the value of the variable. All iden- 
tifiers function as a key that can return a value. So the expression 

<some tag va 1 ue= '${ product ) ' \> 

produces a lookup like this: 

pageContext.get( "product"); 

The EL engine searches each of the four scopes in turn (starting with the 
page scope) until it finds the value. If the search doesn't find the value, it 
returns a null. 



Literals can be one of four types or be null. The four types are 

I 0 * String: Any text enclosed in single or double quotes 

Boolean: The unquoted text, trueorfalse 

V Integer: Any digit from 0 through 9, optionally prefixed with the + (plus) 
or - (minus) sign 

Floating point: Any normal decimal number 

See the JSTL 1.0 specification for exact definitions of the form literals can take. 
You can get the specification from Java .sun . com/products/jsp/jstl . 




Identifiers 



Literals 
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ators available are the standard arithmetic, relational, and logical 
s you would expect to find in a modern programming language. 
However, EL also adds a few new operators. 



The [ J (square bracket) and . (period) operators 

Two of the operators that EL adds are the [ ] (square bracket) and . (period) 
operators. These two operators are similar but the [ ] operator has a wider 
number of uses than the . operator. 

You can use the . operator much like the Java . operator, except rather than 
calling a method, the . operator accesses a property of a bean and is used 
on a variable that references a bean. For example, suppose you have a bean 
named PurchaseOrderthathasa property named vendorName. Furthermore, 
the bean is referenced by a variable named po. You could use an EL expres- 
sion like the following to access vendorName. (We are using JSTL tags in our 
examples, although we do not explain the JSTL tags until the "Core library" 
section later in this chapter.) 

<c:out val ue= '${ po . vendorName ) ' /> 

You could also use the [ ] operator to access vendorName by using this type 
of expression: 

<c:out val ue= '${ po[ " vendorName" ]) ' /> 

However, the . operator is limited to properties of beans, but the [ ] operator 
can also access values stored in arrays, Lists, and Maps. 



The empty operator 

The empty operator solves the problem of an identifier being non-null yet 
essentially empty, such as a zero-length string. Using the unary empty opera- 
tor on an identifier returns true if the identifier is either null or has an empty 
value. This applies to Strings, arrays, Maps, and Lists. Here is an example of 
its use: 

<c:if test= '${ empty po . vendorName ) ' /> 



Implicit Objects 

The EL engine has numerous objects available that you can use in expres- 
sions to retrieve values. You reference the implicit objects by name. Here are 
their names and descriptions: 
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I W pageContext: The PageContext object 

DBOORl 

reqi 



pageScope: A Map object that maps page-scoped attributes to their 

es 



questScope: A Map object that maps request-scoped attributes to 
their values 

sessi onScope: A Map object that maps session-scoped attributes to 
their values 

V appl i cati onScope: A Map object that maps application-scoped attrib- 
utes to their values 

pa ram: A Map object that maps parameter names to a single String value 

i>* paramVal ues: A Map object that maps parameter names to a String 
array of all values 

\S header: A Map object that maps header names to a single String value 

headerVal ues: A Map object that maps header names to a String array 
of all values 

cooki e: A Map object that maps cookie names to a single Cookie object 

i ni tParam: A Map object that maps context-initialization parameter 
names to their Stri ng parameter value 



For example, to retrieve a value from a session attribute called user Name, 
you would use the following: 

< c:out val ue=" ${ sessi onScope . userName ) " \> 

To retrieve the value of a request parameter named acti on, you would use 

< c:out val ue=" $ { pa ram . acti on ) " \> 



Using the Struts-EL Tag Library 

The Struts-EL library is designed to work with the Struts framework. The 
implementations of the tags "know" about the configuration of your Struts 
application and make reference to various Struts components when generat- 
ing the page content. You can find the complete syntax for all the Struts-EL 
tags in Appendix A. 



Getting the Struts-EL tag library 

To use the Struts-EL library, you must include the standard Struts tag library, 
because the Struts-EL library classes are inherited from the Struts library 
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classes. You also need to include the JSTL tag libraries because Struts-El uses 
the expression engine from the JSTL libraries. The libraries struts .jar, 
*t|"wtA^el .jar, jstl .jar, and standard.jar come with the Struts 1.1 



If you intend to use the tags in any of the JSTL libraries — and you should — 
you need to include also the libraries that JSTL needs. You need to download 
these additional libraries separately by retrieving the JSTL implementation 
from the Jakarta Taglibs Web site at 

Jakarta. apache. org/taglibs/doc/standard-l.O-doc/intro. html 

An implementation of JSTL version 1.1 is available, but we have chosen to 
use version 1.0 because version 1.1 requires a Web container that supports 
the JSP 2.0 specification. Tomcat 5.0 supports JSP 2.0, but it is still in beta 
testing at the time of this writing. 

To summarize, to use Struts-EL and JSTL, be sure that you include the follow- 
ing twelve JAR files in your WEB-INF/lib folder. 

struts .jar: The standard Struts tag library, as well as the Struts frame- 
work class files 

V struts el .jar: The EL version of the standard tag library 
i>* jstl .jar: The JSTL API classes 

standard, jar: The JSTL standard taglib implementation 

dom . j a r: Library needed by JSTL 
i>* jaxenful 1 .jar: Library needed by JSTL 

jaxp-api .jar: Library needed by JSTL 
f* jdbc2_0s text, jar: Library needed by JSTL 
i>* s ax . j a r : Library needed by JSTL 

saxpath .jar: Library needed by JSTL 

xal an . jar: Library needed by JSTL 

xerceslmpl .jar: Library needed by JSTL 

The Struts-EL library consists of three separate tag libraries. Each library 
encompasses a particular set of functionality. The Beans-EL tag library is for 
handling JavaBeans. The largest library is HTML-EL, which contains Struts- 
related HTML tags. Finally, Logic-EL provides functionality for performing cer- 
tain logical operations. 




on in the contrib\struts-el\lib folder. 
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Beans-EL library 



s-EL library contains five tags. The common convention is to refer- 
rn with the prefix bean, as follows: 

V <bean : >: Renders an internationalized message string to the response. 
The JSTL fmt :message tag offers the same functionality, so we recom- 
mend you use it instead of bean: message. 

<bean : page>: Exposes a specified item from the page context as a bean. 
The JSTL c : set tag offers the same functionality plus a whole lot more 
and therefore should be used instead. 

f <bean : resource>: Loads a Web application resource and makes it avail- 
able as a bean. The JSTL c : i mport tag performs the same functionality, 
so we recommend its use instead ofbean:resource. 

<bean : si ze>: Defines a bean containing the number of elements in an 
array, Collection, or Map. The size tag is useful because EL doesn't sup- 
port calling a bean's method directly. For example, you can find the 
number of elements in a Collection by calling the size method of the 
Collection. Because s i ze is not a standard getter method (otherwise it 
would be called getSi ze), you can't get the number of elements in the 
Collection directly through an EL expression. Therefore, the Beans-EL 
size tag offers functionality that JSTL does not. 

<bean : struts>: Exposes a named Struts internal configuration object 
as a bean. The struts tag has no equivalent in JSTL because it doesn't 
directly know about Struts components. By using the struts tag, you 
may copy a formbean, forward, or mapping object into the page scope 
and reference it through an i d variable. 



HTML-EL library 

A reasonable question might be why you use a special tag to insert standard 
HTML tags. Why not just write the HTML tags directly? The answer is that the 
HTML-EL tags know about the Struts application configuration and can there- 
fore fill out the HTML tag attributes at runtime. The HTML-EL tags are com- 
monly referenced with the prefix html . 

You might specify an HTML form, for example, by using the html : f orm tag 
from the HTML-EL library. It might look like this: 

<html:form action="pol ist.do" > 

Notice that we listed only the one required attribute, action. Yet when the 
page is generated, the resulting HTML tag is 
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<form name=" poLi stForm" 
method="post" 

action="/webpurchasing/polist.do"> 



The name attribute is looked up in the action-mappings in the struts config. 
xml file. The method attribute uses "post" as the default. And the acti on 
attribute URI has the Web application context prefixed to be relative to the 
Web container context. The other HTML-EL tags also cooperate in this fashion 
with the Struts framework. 

The HTML-EL library is by far the largest of the Struts-EL collection, with 28 
tags. All HTML-EL tags and their syntax are listed in Appendix A. 



Logic-EL library 

The Logic-EL library adds commonly used logic to the JSP page without 
requiring scriptlets of Java code. The common convention is to prefix Logic- 
EL tags with logic. The tags that make up the Logic-EL library are 

i>* <1 ogi c: forward>: Forwards control to the page specified by the speci- 
fied Acti on Forward entry. 

<1 ogi c i terate>: Repeats the nested body content of this tag over a 
specified collection. 

f <1 ogi c match>: Evaluates the nested body content of this tag if the 
specified value is an appropriate substring of the requested variable. 

<1 ogi c messagesNotPresent>: Generate the nested body content of 
this tag if the specified message is not present in this request. 

<1 ogi c messages Present>: Generates the nested body content of this 
tag if the specified message is present in this request. 

f" <1 ogi c notMatch>: Evaluates the nested body content of this tag if the 
specified value is not an appropriate substring of the requested variable. 

V <1 ogi c notPresent>: Generates the nested body content of this tag if 
the specified value is not present in this request. 

<1 ogi c present>: Generates the nested body content of this tag if the 
specified value is present in this request. 

V <1 ogi c redi rect>: Renders an HTTP redirect. 

All the logic tags are unique with the exception of iterate, present, and 
notPresent. The i terate tag has an equivalent JSTL tag in c : f orEach. You 
can render the present and notPresent tags using the c:if tags. 
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Working uritb the JSP Standard 



The JavaServer Pages Standard Tag Library (JSTL) simplifies the life of a page 
author by encapsulating the most commonly used functionality into a set of 
JSP tags. The addition of a simplified Expression Language makes it easier to 
retrieve or set values in application data. 

JSTL offers a lot to the page author. In this section, we review all the tags that 
make up JSTL, offering a synopsis of each tag and an example of how the tag 
might be used. In Appendix A, we provide the syntax for each tag in the 
library. 

JSTL 1.0 has two versions of JSTL: the EL version, which uses the EL expres- 
sion language, and the RT version, which uses the older runtime expression 
language. All our examples use only the EL version. 

JSTL is considered one library, but the implementation divides JSTL into four 
separate libraries: Core, Formatting, SQL, and XML. Each library encompasses 
a particular set of functionality. 



Core library 

The Core tag library provides general functionality that page developers 
commonly need most. The convention is to reference all tags in the Core 
library with the prefix c. 

General-purpose tags 

The general-purpose tags consists of four tags that you use to manipulate 
scoped variables (variables that exist in one of the four scopes — page, 
request, session, or application). They are 

<c : out>: The out tag evaluates an expression and outputs the result to 
the current JSPWriter (responsible for writing out the page contents). 
The following example outputs the value of the vendorName property 
found in the po object stored in the session: 

The vendor is <c:out value="${sessionScope.po. vendorName)"/). 

i>* <c : set>: The set tag sets the value of a scoped variable or a property 
of a target object. For example, use the following to set a scoped vari- 
able named "currentResi dent": 

<c:set var=" cur rent Resident" val ue="${sessionScope. customer. name)"/) 
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To set the "city" property of the " customer . address" target object, 
use the following: 

set target="$(customer.addressl" property="city" val ue=" $ I po . ci ty I " /> 



remove>: The remove tag removes a scoped variable from the scope. 
To remove the "cur rent Resident" variable from the page scope, use 
the following: 

<c: remove v a r=" cur rent Resident"/) 

<c: catch>: The catch tag catches an exception (j ava . 1 ang . 
Throwabl e) in a nested block. For example, to catch an exception in a 
set of tags, use the following: 



<c:catch var="theException") 


<c:out val ue=" $ { po . poNumber I " /> 




. . . other tags . . . 




</c:catch> 




< c : i f test="$(theException != null)") 






Oops! An error occurred. 






</c:if) 







The theException variable holds an Exception if one is thrown in the 
c : c a t c h body. 



Conditional taqs 

Conditional tags support the conditional execution of various enclosed page 
elements based on the evaluation of one or more expressions. Two basic tags 
are available, a simple conditional tag and a mutually exclusive tag: 

<c : i f >: The simple conditional is the i f tag. If the expression evaluates 
to true the body of the i f tag is executed. For example: 

< c : i f test="${customer. accesses == 11") 

This is your first access. Welcome to the Blah-Blah Web site. 
</c:if> 

V <c: choose>, <c :when>, and <c : otherwi se>: In the body of choose 
you define the mutually exclusive conditions by using the when tag. If 
none of the when conditions are t r u e , the optional otherwise tag is 
executed. For example: 



<c:choose) 






<c:when test= 


'${po.tag == 


'save' )") 


</c:when) 






<c:when test= 


'Slpo.tag == 


'update' )") 


</c:when) 






<c:when test= 


'${po.tag == 


'delete' 1") 
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</c:when> 
<c:otherwise> 

</c:otherwise> 
choose) 



Iterator tags 

The iterator tags provides a looping mechanism to iterate over a wide variety 
of collections of objects. Two very flexible tags are available to accomplish 
this: 



v 0 <forEach>: The f orEach tag repeats the body content once for each 
element in the collection of objects it is iterating over. The collection of 
objects can be any implementation of java.util .Col lection, Java . 
util .Map, java.util .Iterator, Java. util .Enumeration,an array, 
and even a Stri ng of comma-separated values. Here is an example iter- 
ating over a collection of purchase orders and writing out the purchase 
order number of each purchase order: 

<table> 

<c:forEach var="po" items="${purchaseorders)"> 

<tr><td><c:out val ue="$ { po . poNumber ) "/X/tdX/tr> 
</c:forEach> 
</table> 

Here is a similar iteration, but this time the collection of objects is of the 
type java.util .Map. Each item from the map will be of type Java . uti 1 . 
Map . Entry and have two properties, key and val ue. The example out- 
puts the value property: 



<table> 






<c:forEach var= 


"ponumber" 


items="${ponumbers)"> 


<tr><td><c 


out value= 


"$ {ponumber. val ue)"/X/tdX/tr> 


</c:forEach> 






</table> 







You may also use the f o r E a c h tag to iterate over a particular range of 
numbers, with a starting and ending number as well as a number to 
increment by. Here is an example that iterates 11 times, from number 
100 to 110. 

<c:forEach var="i" begi n=" 100" end="110"> 

<c:out value="${i !"/> 
</c:forEach> 

Finally, you may need to know the particular iteration number you are 
currently on. You may define the varStatus attribute and retrieve the 
count property from that variable. Here is an example: 
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<table> 

<c:forEach var="purchaseorder" itens="${purchaseorders|" 
varStatus="status"> 
<tr> 

<td><c:out val ue="${ status. count I" /></td> 
<td><c:out val ue="$ { purchaseorder . poNumber ) "/X/td> 
</tr> 



</c:forEach> 

</table> 

<c: forTokens>: The f orTokens tag is similar to the f orEach tag 
except f orTokens iterates over a set of tokens (user-defined entities) 
that are separated by the delimiters supplied as an attribute. The set of 
tokens are enclosed in a Stri ng. Here is an example of using f orTokens 
with a " ; " delimiter: 



<table> 






<c:forTokens var="al phaval ue" itens=" 


i;b;c;r,s;w;z" del i m s = 


= ";"> 


<tr><td><c:out val ue="$ ( al phaval u 


!U/X/tdX/tr> 




</c:forEach> 






</table> 







URL-related tags 

Four URL tags support linking, importing, and redirecting: 

V <c: import>: The import tag is designed to overcome some of the 
memory-related inefficiencies of the <jsp:include> tag. Using the 
import tag, you may import a context-relative URL, a page-relative URL, 
a foreign-context URL (in a different Web application but in the same 
Web container), or an absolute URL. The contents of the imported 
resource are written out as text to the current JSPWriter. This example 
imports a resource with a relative URL from the same context: 

<c:import url ="/header . html " /> 

This example imports a resource with a relative URL from a different 
context in the same Web container: 

<c:import url = " /footer . j sp" context="/sampl e" /> 
This example imports a resource with an absolute URL: 

<c: import url = " http : //www. othenos . com/pol i st?accept=true" /> 

V <c: url >: The url tag takes care of rewriting URLs, if necessary, and pre- 
fixing the context to context-relative URLs. 




Rewriting URLs is a technique used to a change a URL for various purposes. 
The u r 1 tag rewrites the URL when a browser does not accept cookies because 
you need to store session information about the user. The u r 1 tag embeds the 
session information (specifically, the session ID) in the URL. In this way, when 
the browser submits a request, the session information is sent also. 



Part III: Expanding Your Development Options 



DBooks 



Here is an example of using the url tag to process a URL and then using 
that processed URL in an h re f tag: 



url val ue="/pol i st" var="thellrl" /> 
href='<c:out val ue="$ { theUrl ) "/> ' >Purchase Order</a> 



\^ <c: redi rect>: The redi rect tag sends an HTTP redirect request to 
the browser for a new URL, as in this example: 

<c:redirect url="http://www. nun.edu/registrar" /> 

<c: param>: The three previous tags (i mport, url , and redi rect) can 
accept parameters in the body content of the tag. You use the pa ram tag 
to specify those parameters. You must specify a name and value attribute 
for each parameter. Here is an example of the pa ram tag used with the 
url tag: 

<c:url val ue="/pol i st" var="theUrl" > 

<c:param name="user" value="${user.userNanel"/> 

<c:param name="country" val ue="$l user.country ["/> 
</c:url> 

<a href='<c:out val ue="$ (theUrl !"/>'> Regi ste r </a> 

The parameter attributes are also encoded as part of the processing. 

URL encoding refers to the process of encoding special characters in a 
string. For example, you must encode a space in a URL parameter string 
as a '9620', as in this example: 

webpurchasing/pol i st?user=TomX20Jones&country=Uni tedKOKingdom 

Most often you represent the offending character as %hh, where hh are 
two hexadecimal digits representing the US ASCII value of the character 
(assuming that you're using the US ASCII character set). Only the follow- 
ing characters may appear in URLs without encoding: 



0 through 9, a through z, A through Z, and 



+ !*'() 



Formatting library 

The tags available in the Formatting library, especially the internationalization 
tags, provide the page author with a simple mechanism to internationalize 
the page. The prefix used for the Formatting library is most commonly f mt. 
(We discuss I18N issues in Chapters 3 and 6, so we won't discuss them in 
detail here.) 

Internationalization taas 

The six tags in the internationalization grouping deal explicitly with I18N 
issues. These tags use Locales and Resource Bundles to do their work, as we 
discuss in Chapter 6: 
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f <fmt: setLocal e>: This tag sets the locale for subsequent international- 
ization tags. If you use this tag, browser-based locale setting capabilities 
^disabled. Here is an example of setting the locale: 

't:setLocale val ue="en_US" /> 

The value can be either a 2 letter language code (and optionally an under- 
score followed by a 2-letter country code) orajava.util .Locale object. 
When using this tag, be sure to set it at the beginning of the page because 
all the other internationalization tags depend on it. 

V <fmt: bundl e>: The bundl e tag allows you to set a specific resource 
bundle for use in a narrow context, the body of the bundle tag. For 
example: 



<fmt:bundle basename= 


'Label s 


> 


<fmt:message key= 


'pol i st 


find. label"/) 




<fmt:message key= 


'pol i st 


find. all"/) 




</fnt:bundle> 









In the body of the bundle tag, the messages will look up their keys in the 
resource bundle named "Labels". 



\S <fmt: setBundl e>: The setBundl e tag specifies the resource bundle to 
use globally in the page, request, session, or application scope. Once 
set, all messages use that resource bundle to look up their keys and 
retrieve the message text. The only exceptions are message tags 



enclosed in a bu 
bundle: 


ndl e tag. Here is an example of setting a resource 


<fmt: setBundl e I 


asename="Err 


ors" var="err 


orBundle" /> 





In this example, the resource bundle named Errors is used to retrieve 
messages. This particular localization context (the Locale and Resource 
Bundle being used) can be referenced by the errorBundle variable. The 
use of the va r attribute is optional. 



f <fmt :message>: You may output an I18N message using the message 
tag. This tag retrieves the message content based on the supplied key 
and the current resource bundle, as in the following example: 

<fmt: mess age key="errors.db. connection"/) 

<fmt : pa ram>: You can add parameters to messages to provide specific 
information to the user. You can pass these parameters to the message 
by using the p a r a m tag in the message tag's body. For example: 

<fmt: mess age key="errors.db. connection") 
<fmt:param val ue="${user.userNamel"/) 
</fmt:message) 
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The message associated with the " error. db. connect ion" key might be 

errors. db. connect!' on=A connection error occurred for {01 



requestEncodi ng>: When a browser encodes a response's form 
using a character set other than the default character set, you will 
likely have trouble with the form's data. This is because most browsers 
don't handle the content type properly. Use of the requestEncodi ng tag 
ensures that the encoding is correct. Use this tag when you're expecting 
nondefault character-set encoding: 

<fnt:reqjestEncoding /> 



Formatting tags 

The following six tags enable you to format dates, times, and numbers in a 
locale-specific or customized manner: 



v 0 <fmt : ti meZone>: This tag specifies the time zone to apply to the for- 
matting tag that you place in the body of the ti me Zone tag. An example 
of this tag is shown here: 



<fnt:timeZone value="GMT+l:00"> 
<fmt:formatDate val ue="${now) 
timeStyl e="f ul 1 "/> 
</fmt:timeZone> 



type="both" dateStyle= 




The now variable is assumed to represent a Date object. The ti me Zone 
value attribute can be a string with a time zone ID, a string with a custom 
ID supported by the Java language, or a Java . uti 1 .TimeZone object. See 
the documentation on Java . uti 1 .TimeZone for more information. 

<fmt: setTimeZone>: This tag sets the default time zone for the page, 
request, session, or application scope. It replaces the previous default 
time zone. The setTimeZone tag is similar to the timeZone tag except 
there is no body and you can specify the scope, if desired. The following 
example sets the time zone as U.S. Pacific Time in the session scope. 
The default scope is page: 

<fmt:setTimeZone val ue="America/Los Angles" scope="session"/> 

<fmt: f ormatNumber>: The fmtNumber tag can format a number, cur- 
rency, or a percentage in a locale-specific or custom manner, as shown in 
this example: 

<fmt:formatNumber val ue=" 9876543 . 21 " type="currency"/> 

This example formats the number 9876543.21 in a currency format spe- 
cific to the current locale for the page. If the locale were en_US, the 
number would appear as 

$9,876,543.21 
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However, if the locale were f r_CH (French, Switzerland), the number 
would appear as 

k 9'876'543.21 

value attribute is the only required attribute if there's no body to 
the tag. Otherwise, value can appear in the body. Eleven other attrib- 
utes offer you complete control over how the number is formatted. 

i>* <fmt:parseNumber>:The parseNumber tag is the opposite of the format 
Number tag. It takes a String as input and produces a Number. You would 
want to use this tag when you have to perform calculations on a number 
that exists as a String. The following is an example of its use: 

<fmt:parseNumber val ue=" $ { cur I " type="currency" var="money"/> 

This example parses the String representation in the cur variable and 
stores the resulting number in the money variable. The type of format- 
ting used is currency. 

V <fmt: formatDate>: The f ormatDate tag formats dates and times into a 
locale-specific or custom format. For example: 

<jsp:useBean id="now" cl ass=" java . uti 1 . Date" /> 

<fmt:formatDate value="$lnow)" timeStyl e="l ong" dateStyl e="l ong"/> 

The example produces the following output for the U.S. locale: 



October 31, 200: 


11:00:03 AM 


CST 






and this for the 


7 rench locale 








31 octobre 2003 


11:00:03 GMT- 


07:0 







Many options for formatting are available, including specifying a pattern 
as used injava.text.SimpleDateFormat. 



<fmt : parseDate>: The parseDate tag is the opposite offormatDate.lt 
expects a String value of a Date and creates a j ava . uti 1 . Date object 
that's stored in a variable or output with JSPWriter: 

<jsp:useBean id="now" cl ass=" java . uti 1 . Date" /> 

<fnt:fornatDate value="${nowl" dateStyl e="l ong" var="rightNow"/> 

<fmt:parseDate val ue="${ rightNowl " va r=" real Date"/) 

This example takes therightNow Date String created bytheformatDate 
tag and stores it as java. uti 1 .Date in the real Date variable. 



SQL library 

The SQL Library provides the page author with a means to access an SQL data- 
base directly from the JSP page. Of course, this technique breaks all the rules 



DropBooki 



Part III: Expanding Your Development Options 



ivioaei iayi 

DBodte 

the SOL lil 



about separation of concerns, the encapsulation of database operations in the 
Model layer, and many other good programming practices. Yet, in some circum- 
ou may find it useful to have direct SQL access, such as in very small 
ns, prototyping, or just trying out a creative idea. Six tags make up 
the SQL library. Together they provide the basic functionality to interact with 
a SQL database, such as establishing a connection, querying, updating, deleting 
and inserting data, and transactions. The SQL library most commonly uses sql 
for its prefix. 

You are required to establish a data source before you can use the tags in the 
SQL library. You can establish a data source in a simple way by declaring the 
JDBC parameters for your database in the tag you're using. This means speci- 
fying the URL, driver, username, and password when setting the data source 
using the setDataSource tag. 

If you've already configured a data source in Struts, another possibility is to 
create a startup class (by extending the PI ug I n interface — see "Implementing 
Your Own Plug-in" in Chapter 9) that adds the data source to the JSTL configu- 



ration file. The i n i t method would have code like the following: 




// assume we have a reference to the Servl etContext 
// assume your data-source is named "mssql" in strut 
// get a reference to the data source 
DataSource dbConnMgr = ( DataSource )sc . getAttri bute( ' 
// set the data source into the JSTL Config file 
Conf ig.set(sc, Conf i g . SQL_DATA_SOURCE , dbConf i gMgr ) ; 


in " s c " 

s -conf i g 

mssql " ) ; 













This code has the advantage of not having to bother with specifying a data 
source in any of the SQL tags. 



The six tags of the SQL library are 



f" <sql : query>: The query tag allows you to specify an SQL query string 
and return the results in a variable whose type isjavax.servlet.jsp. 
j st 1 .sql .Re suit. You can then iterate the results to extract the values 
Here is an example of a query tag and then extracting the results: 



<sql :query var="purchaseorders" 


> 


SELECT * FROM purchaseorders 




WHERE country = ' France' 




ORDER BY lastname 




</sql :query> 




<table> 




<c:forEach var="row" iterns=" 


${ purchaseorders . rows ) "> 


<tr> 




<td><c:out value="${ 


purchaseorders .vendor Name) "/></td> 


<td><c:out value="${ 


purchaseorders .address 1 "/></td> 


<td><c:out value="${ 


purchaseorders .phone 1 "/></td> 


</tr> 




</c:forEach> 




</table> 
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I <sql : update>: To insert, update, or delete data from the database, you 
use the update tag. You may use ? in the SQL as a parameter place- 
I Jna^er in the same manner as with the Java . sql . Prepa redStatement 
ftp^s. See the Java API for more details. This example supplies two para- 
meters to the SQL statement by using the pa ram tag: 

<sql : update) 

UPDATE account 
SET Balance = Balance - ? 
WHERE accountNo = ? 
<sql :param value="${transterAnount|"/> 
< sql :paran value="${accountFrom)'7) 
</sql : update) 

See the section on the p a r a m and dateParam tags for further explanation. 

is* <sql : transacti on>: The transact!' on tag provides transaction capa- 
bilities to query and update tags. The transact!' on tag encloses one or 
more query tags, or update tags, or both. If no exception is detected, 
the transaction is committed, or saved. Otherwise, the transaction is 
rolled back (all actions are reversed). Here is an example: 

<sql rtransaction dataSource="$(dataSource)"> 
<sql : update) 

UPDATE account 
SET Balance = Balance - ? 
WHERE accountNo = ? 
< sql :paran value="${transTerAmount)'7) 
< sql :paran value="${accountFron)'7) 
</sql : update) 
<sql : update) 

UPDATE account 
SET Balance = Balance + ? 
WHERE accountNo = ? 
<sql :paran value="${transTerAmount)'7) 
<sql :param value="${accountTol'7) 
</sql : update) 
</sql transaction) 

is* <sql : setDataSource>: This tag sets the data source for the page, 
request, session, or application depending on the scope you choose. 
Page scope is the default. You may specify the data source using JDBC 
parameters, as in the following example, or you may use an instance of 

javax.sql .DataSource: 

<sql : set Data Source url = "jdbc: JTurbo: //local host/Purchasing" 
driver="com.ashna.j turbo. driver. Driver" 
user="webpurchaser" 
password="purcha$e" /) 

is* <sql : param> and <sql : dateParam>: Both tags supply values to para- 
meter markers (?) in an SQL statement used in the query and update 



DropBoo 



Part III: Expanding Your Development Options 



tags. The pa ram tag provides any value except a j ava . uti 1 .Date type; 
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that value is provided by the dataParam tag. The sequence of the p a r a m 
datePa ram tags in the body of the query and update tags must 
h the use of ? in the SQL string. 



XML library 

The XML library handles XML documents and is based on XPath, a W3C 
(World Wide Web Consortium, the official standards body for the Web) rec- 
ommendation for selecting and specifying the parts of an XML document. 
The use of XPath for XML documents expands on the expression language 
used by the other libraries of JSTL. The description of XPath is beyond the 
scope of this book. For a nice tutorial on XPath, go to 



www. w3school s.com/xpath/default.asp 



The XML library provides many of the same functions for XML documents as 
described previously in this section: core tags for commonly used functional- 
ity, flow control tags for conditional and iterative functions, and transform 
tags for transforming XML documents with XSLT The prefix x is the conven- 
tion for the XML Library tags. 



XML core tags 

The XML core tags follow: 

i>* <x: parse>: Parses an XML document and stores the resulting object 
into a scoped variable. 

<x: out>: Evaluates an XPath expression and outputs it to the current 
JSPWriter. 

<x: set>: Evaluates an XPath expression and stores the result in a 
scoped variable. 



XML ftou? control tags 

All tags in the XML flow control group are identical to the tag in the Core 
library except that they take XPath expressions instead of EL expressions. 
The tags are i f , choose, when, otherwi se, and f orEach. 



XML transform tags 

The two XML transform tags follow: 



i>* <x: transf orm>: Applies an XSLT stylesheet to an XML document and 
outputs the resulting transformation. 

f <x : pa ram>: Used in the transform tag's body to supply transformation 
parameters. 



Chapter 10: Getting a Helping Hand with Tag Libraries 



Other Struts Tag Libraries 

ipBooks 

Dlins in tl 



dditional Struts-specific tag libraries are available. We offer a sam- 
pling in this section. 



Tites library 



The jsp : i ncl ude tag allows the page developer to include or insert other 
resources into a page at runtime. For example, rather than duplicate common 
header and footer information on each page of a Web application, the devel- 
oper can simply use jsp : i ncl ude to insert the pages that contain the header 
and footer definitions. 

The general idea behind the Tiles library is to augment and expand on the 
j s p : i n c 1 u d e tag by providing ways to 



Define the structure of pages by using a template 
Extend templates through inheritance 
Support internationalization 
V Integrate with the Struts framework 

In Chapter 1 1, we show you how to leverage the Tiles library to your advantage. 



Struts-Layout library 



The Struts-Layout tag library is a powerful, open-source, custom tag library 
to aid the page author in the creation of user interface elements. It offers: 



Specialized input fields that offer controlled access and display These 
input fields are similar to the Struts HTML-EL library but offer additional 
functionality, such as displaying error messages next to the field and 
visually marking required fields. 

Powerful and flexible display of collections, including sorting and paging. 

Layout definitions to control the arrangement of elements on the page. 

Control over the page's look-and-feel through skins (a way of specifying 
color combinations and styles for an entire application). 



u 0 Custom formatting of text information. 
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The JSTL and Struts-EL libraries provide some of the functionality found in 
the Struts-Layout library However, if you need to format and manage lists of 
should investigate the use of Struts-Layout. 



The Struts-Layout home page is struts . appl i cati on servers .com. 



bispiay library 



Although not specifically made for Struts, the Display tag library focuses 
exclusively on displaying collections in a table format. The Web site describes 
the functionality succinctly as, "Give it a list of objects and it will handle 
column display, sorting, paging, cropping, grouping, exporting, smart linking 
and decoration of the table in a nice and customizable xhtml style." Figure 
10-1 is a sample of the output you could expect. 

You can find more information at the Display tag Web site at 

displaytag.sourceforge.net/index. html 



Figure 10-1: 

Sample 
table display 
using the 
Display 
library. 



20 items found, displaying 1 to 8, 
[FirsVPr e v]l,2,3[N 0 xt/Lajt] 







CITY PROJECT 


HOURS TASK 






Carthago Army 


236,0 rebum gubergren sed du 






29.0 sanctus labore tempor duo 




Arts 


932,0 nonumy irividunt sea san 


ctu 




862.0 erat sed tempor At 






Gladiators 


525.0 duo sed diam dolores 








558,0 voluptua voluptua elitr k 


Id 




Neapolis Army 


933,0 diam elitr clita dolore 






B60.0 diam diam sadipscing sit 






Export options: £1 CSV | g 


Excel | <>) XML 







Looking at Jatfa Server Faces 

Java Server Faces (JSF) is touted as an evolutionary jump in the way J2EE 
Web applications are created. By standardizing the way developers construct 
user interfaces (UI) in J2EE Web applications, JSF can make the developer's 
task a lot easier, as well as make the resulting Web application more flexible. 

JSF is a framework that offers the following benefits: 

Provides a rich palette of UI components that are device independent 

V Offers a standardized, server-based event handling mechanism for UI 
components 

Maintains page state automatically 
Includes a validation framework 
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David Geary, a member of the JSF specification team, likens JSF to a combina- 
tion of Struts and Swing — the strong lifecycle management capability of the 
ntroller married to the rich UI components and event model of Swing. 



This brings up the question of how JSF will affect the future of Struts. Will it 
replace Struts? The answer seems to be a resounding no. As it turns out, one 
of the two JSF specification lead members is Craig R. McClanahan, the principle 
developer of Struts. In a recent mailing list posting, Craig stated that Struts will 
have, "... a very clean integration with JSF, so that you can use JSF compo- 
nents in your user interface, but continue to use the controller, Actions, and 
associated business logic." 



To that end, Craig has been developing a library called struts-faces that 
will accomplish the smooth integration between JSF and Struts. You can 
download this library by downloading the source code for the latest Struts 
nightly build at 

archive. apache. org/dist/jakarta/struts/old/rel ease/struts -faces 

The bad news is that you have to build the JAR file yourself. The good news 
is that the download provides an Ant build file. (We discussed the Ant devel- 
opment tool in Chapter 2.) The source code and bui 1 d . xml file are in the 

contri b/struts-f aces folder. 



Currently, the specification for JSF (Java Specification Request 127) is still in 
the review process. Therefore, the only implementations of the technology 
are based on a moving target (the changing JSR). The latest reference imple- 
mentation is labeled EA4. You can download it at 



Java. sun. com/j2ee/javaserverfaces 



If you're interested in experimenting with Struts and JSF, the Struts Web site 
contains instructions for integrating the two technologies. See the following 
for more information: 

j a karta. apache. org/struts/proposals/struts -faces. html 

Here are some additional JSF resources that you may find helpful: 

www . j sf cent ral . com/i ndex . html : A nice JSF portal that links to many 
JSF resources. 

www. j avaworl d . com/ j avaworl d/ j w- 1 1 -2002/ jw-1 129 - jsf . html: 
David Geary has written three very readable articles on JSF. The first one 
is at this URL. From there, you can find links to the other two articles. 

j ava . sun . com/ j2ee/j avaserverf aces: The home page for JSF. 

j^jcp.org/en/jsr/detail?id=127: The JSR-127 specification. 
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Working with the Tiles Framework 



■ M /hen your Web application starts expanding beyond a few pages into 
WW the realm of dozens or even hundreds of pages, maintenance becomes 
an important issue. With so many pages to keep up to date, you're thinking of 
ways to do less and accomplish more. One easy way to save work is to isolate 
content that is repeated on many pages, such as header and footer informa- 
tion. If you can isolate this information into separate files and only reference 
it on each page, life would be a lot easier, at least when you need to modify a 
header or footer for the site. 



Making \lour Page Layout Life Easier 

A sample JSP page that is full of opportunities for refactoring — rewriting por- 
tions of code to make the resulting code simpler, more readable, and more 
efficient — is shown in Listing 1 1-1. This page is similar to the logged in.jsp 
page we created in Chapter 3 except that we added logo and footer informa- 
tion to make the page more representative of a production page. We will use 
this page to show how you can use page composition techniques to maintain 
pages more easily. 



Listing 11-1 Sample JSP Page, refactor.jsp 



1 <!-- begin the taglib definitions --> 

2 <%@ taglib prefix="c" uri="/WEB-INF/c.tld" %> 

3 <%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %> 

4 <%@ taglib pref i x=" html " 
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uri=" /WEB- INF/struts -html -el . t 1 d " %> 
<!-- end the taglib definitions --> 



1 : html 1 ocal e="true" /> 

7 <head> 

8 <fmt : setBundl e basename="Appl i cati onResources" /> 

9 <ti tl eXfmt :message key=" 1 ogi n . ti tl e" /></ti tl e> 
10</head> 



ll<body> 



12 <!-- begin the logo for the application --> 

13 <table width="100%"> 

14 <tr valign="top" al ign="center"> 

15 <td> 

16 <img s rc=" i mages/webLogo . gi f " 

name="webLogo" 

width="425" height="50" border="0"> 

17 </td> 

18 </tr> 

19 </table> 

20 <! -- end of logo --> 



21 <h2> 

22 <fmt:message key=" 1 oggedi n . msg" > 

23 <fmt:param val ue= ' $ { requestScope . userName ) ' /> 

24 </fmt : message> 

25 </h2> 



26 <!-- begin the footer for the application --> 

27 <div al ign="center"> 

28 <hr SI ZE=" 1 " WIDTH="100%"Xbr/> 

29 Comments or Questions? 

30 <a href = ' mai 1 to : support@othenos . com ' > 

Email Othenos Customer Support</aXbr/> 

31 ©2003 Othenos Consulting Group<br/> 

32 </div> 

33 <!-- end of footer --> 

34</body> 
35</html > 

In examining the page makeup in Listing 11-1, three areas stand out as possi- 
bilities for common content: 

f* The definitions of the tagl i bs between lines 1 and 5 
I *<" The inserted logo in lines 12-20 
The footer section in lines 26-33 



You can assume that other pages in the Web application are similar in 
structure — they include the same taglib definitions, logo graphics, and 
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footer information. Because these code snippets are common to so many 
other pages, you could simplify the code a lot by removing these repeated 
and putting them into their own separate files. Then the original 
t contained the snippets could reference this content using the 
directive and j sp : i ncl ude tag. 



You can extract the common features and put them into three separate files, 
as shown in Listings 11-2, 11-3, and 11-4. 



Listing 11-2 taglibs.jsp 



<%@ taglib prefix="c" uri = " /WEB- 1 NF/c . tl d" %> 

<%@ taglib pref i x="fmt" uri = " / WEB- INF/fmt . tl d" %> 

<%@ taglib pref i x=" html " uri="/WEB-INF/struts-html -el .tld" %> 

<%@ taglib pref i x="ti 1 es " uri =" /WEB- 1 NF/struts-ti 1 es . tl d" %> 



Listing 11-3 logo.jsp 



<table width="100%"> 

<tr valign="top" al i gn="center": 
<td> 

<img src = "images/webl_og( 
width="425" height= 

</td> 
</tr> 
</table> 


> 

3.gif" name="webLogo" 
="50" border="0"> 


Listing 11-4 footer.jsp 











<div al i gn="center"> 

<hr S I Z E = " 1 " WIDTH="100%"Xbr/> 

Comments or Questions? 

<a href = ' mai 1 to : support@othenos . com' > 



Email Othenos Customer Support 
</a><br/> 

©2003 Othenos Consulting Group<br/> 
</div> 



Simplifying With Includes 

You can use three elements to insert outside content into a JSP page: the 
i ncl ude directive, the jsp : i ncl ude tag, and the JSTL c : import tag. 

The JSP i ncl ude directive allows the insertion of static content into the JSP 
page at the time the page is converted into a Java class by the JSP engine. 
This directive has the following syntax: 
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<%@ include f i 1 e = " rel ati vellRLspec"%> 
s of the tag follow: 

tag can place only static content in a JSP file, such as an HTML or 
JSP file. 

v 0 The tag is processed only when JSP is converted into a Java class, not at 
request time. 

f" If the included file is updated, JSP containers are not required to change 
the converted page to include new content. 

Listing 11-2 shows the use of the i ncl ude directive to insert the tagl i bs . jsp 
segment into the loggedin.jsp page. You must include the tagl i bs . j sp 
in the page before the page is converted to the Java class because the tags 
that the page uses (html , c, f mt, tiles) require that you define the library 
before the conversion can occur. The library definition is in the tagl i bs . jsp 
file. Inserting tagl i b s .jsp at request time would be too late. Here is how you 
would insert it before the page is converted: 

<!-- begin the tagl i b definitions --> 
<%@ include f i 1 e="tagl i bs . jsp" 1> 
<!-- end the tagl i b definitions --> 

To include content at request time, you can use the jsp : i ncl ude tag. This 
tag can insert both static and dynamic content into the page when the page 
is requested. The following is the syntax for j sp : i ncl ude: 

<jsp:include page=" rel ati veURLspec" f 1 ush="true | f al se"/> 

Highlights of the tag are as follows: 

The tag can include static (for example, HTML) or dynamic (for example, 
JSP) content. 

Inclusions are processed at request time. 
v 0 You can pass parameters to the included content. 

f* The JSP container is aware when an included resource changes and gen- 
erates new content based on the new file. 

v* The flush attribute defaults to fal se. If set to true, it indicates that the 
page, if buffered, should be flushed (written out) before including the new 
resource. 
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The 1 ogo . j sp and footer, jsp segments (Listings 11-3 and 11-4) are candi- 
dates for including with the j s p : i n c 1 u d e tag. Here is how they would look if 
ded them with jsp : i ncl ude: 



egin the logo for the application --> 
<jsp:include page="l ogo. jsp" flush = "true" /> 
<!-- end of logo --> 



<!-- begin the footer for the application --> 
<jsp:include page="f ooter . jsp" flush="true" /> 
<!-- end of footer --> 



You may want to use the c : i mport tag from the JSTL library instead of j sp : 
i ncl ude. The c : import tag claims to reduce some of the buffering inefficien- 
cies found in the j s p : i n c 1 ude tag. Another feature of the tag is its ability to 
retrieve resources from any URL. The j sp : i ncl ude tag is limited to resources 
in the same context as the current page. The simplest syntax for the c : i mport 
tag is 

<c:import url="ur7" /> 



Here is how you might use the c : i mport tag instead of jsp : i ncl ude in the 
preceding example: 

<!-- begin the logo for the application --> 
<c:import url="l ogo. jsp" /> 
<!-- end of logo --> 

<!-- begin the footer for the application --> 
<c:import url="footer. jsp" /> 
<!-- end of footer --> 



You can use c: import or jsp:include interchangeably depending on the 
tag libraries you prefer. 

In Listing 11-5 we show how the original JSP in Listing 11-1 looks after refac- 
toring and using i ncl udes to retrieve the common information. We use the 
c : import tag for including, with the exception of including the tagl i bs . jsp 
(line 2). Tagl i bs . j sp must be included when the page gets converted to a 
Java class because other tags in the page depend on the tag library defini- 
tions found intaglibs.jsp. Therefore the JSP i n c 1 u d e directive must be 
used. 
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~ begin the taglib definitions --> 
include f i 1 e=" tagl i bs . j sp" %> 
end the taglib definitions --> 

4 <html : html 1 ocal e="true" /> 

5 <head> 

6 <!-- begin the header for the application --> 

7 <f mt : setBundl e basename="Appl i cati onResources" /> 

8 <title><fmt:message key=" 1 ogi n . ti tl e" /></ti tl e> 

9 <!-- end of header --> 
10</head> 



ll<body> 



12 


<!-- begin the logo for the application --> 


13 


<c:import url = " 1 ogo . jsp" /> 




14 


< ! - - end of 1 ogo - -> 




15 


<H2> 




16 


<f mt : mess age key=" 1 oggedi n . msg" > 




17 


<f mt :param value='${requestScope.userName) 


18 


</fmt : message) 




19 


</H2> 




20 


<!-- begin the footer for the application --> 


21 


<c:import url ="f ooter . j sp" /> 




22 


< ! - - end of footer - -> 





23</body> 
24</html > 



You can use i ncl udes to ref actor all the JSP pages in the application that 
have a similar structure. By doing so, you dramatically reduce the amount of 
effort necessary to make changes to the common parts of the pages because 
you need to edit only one copy of each common segment. Any change to 
common content automatically ripples through every page that includes 
the segment. See Figure 11-1 for a graphical representation of the process. 

Although refactoring and using i ncl udes offer many advantages to the alter- 
native of all-in-one JSP pages, the resulting pages still have a maintenance 
problem. The structure or layout of the page is defined in the page. In other 
words, each JSP page must define how it will be laid out. If that layout changes 
(and it will over time), all pages need to be reworked to accommodate the 
new arrangement. Fortunately, a solution to that problem exists: the Tiles 
framework. 
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Figure 11-1: 

Diagram 
showing 
page 

composition 
using the 
includes 

mechanism. 
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framework expands on the use of i ncl udes by providing the devel- 
oper a way to define a common look-and-feel in a template (sometimes called 
a layout). The template defines how the page should look but not what con- 
tent should go into it. The template includes the page markup that describes 
the structure of the page, as well as names the additional segments that the 
page should include as content. These additional segments are called tiles. 

If you want a JSP page to take advantage of the Tiles framework, you reference 
the template to use the template's structure as the page's own. You then choose 
tiles that should be inserted into the structure as content. The resulting page 
displays the structure as defined by the template along with the content as 
defined by the tiles it uses. 

An example will help clarify how the Tiles framework works. For this exam- 
ple, we use the final JSP page from the preceding section (Listing 11-5) as the 
starting point. This page contains the structure of how the page should be 
presented and references most of the content required to fill the structure. 
The only content that is part of the page is the body, which consists of lines 
15-19. To make a general structure, you can remove lines 15-19 and create a 
new page segment called 1 oggedi nBody . jsp as shown in Listing 11-6. Notice 
the i ncl ude directive on the first line to add tag library definitions. You need 
the i ncl ude directive because of the custom tags in the page. Each tile that 
is a JSP page must be complete enough that the JSP engine can convert the 
code in the tile to a Java class. 



Listing 11-6 loggedinBody.jsp 



<7o@ include f i 1 e = "tagl i bs . jsp" %> 
<H2> 

<fmt : mess age key="l oggedi n.msg"> 

<fmt : param val ue= ' $ { requestScope . userName j ' /> 
</fmt :message> 
</H2> 



Now you can use the structure to create a template. To do so, you need to 
understand a couple of the Tiles tags, in particular, the ti 1 es : i nsert and 
the ti 1 es : getAsStri ng tags. The ti 1 es : i nsert tag is used specifically in 
the template page. This tag tells the Tiles framework to insert a tile identified 
by the name attribute into the structure at a specific point. Note that the name 
attribute is not the name of a tile or page segment, but an ID that the JSP page 
that references the template will use. 

The ti 1 es : getAsStri ng tag allows you to pass a value to the structure and 
substitute that value for the tag. In a sense, this tag is a parameter-passing 
mechanism for templates. To understand the functionality of both of these 
tags, look at the JSP page that uses the template, as shown in Listing 11-7. 
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Listing 1 1 -7 Simplified JSP Structure Defined as a Tiles Template, 
mainTemplate.jsp 

begin the taglib definitions --> 
include f i 1 e=" tagl i bs . j sp" %> 

3 <!-- end the taglib definitions --> 

4 <html : html 1 ocal e="true" /> 

5 <head> 

6 <!-- begin the header for the application --> 

7 <fmt : setBundl e basename="Appl i cati onResources" /> 

8 <ti tl eXti 1 es : getAsStri ng name=" ti tl e" /></ti tl e> 
9 

10</head> 
ll<body> 

12 <!-- begin the logo for the application --> 

13 <ti 1 es : i nsert attri bute= ' 1 ogo ' /> 

14 <!-- begin the body --> 

15 <ti 1 es : i nsert attri bute= ' body ' /> 

16 <!-- begin the footer for the application --> 

17 <ti 1 es : i nsert attri bute= ' footer ' /> 

18</body> 
19</html > 

In examining this example, notice that it is a valid JSP page. The JSP page 
defines a structure that all pages that reference the template will contain. In 
addition: 

i>* Line 8: Specifies a parameter with the name of t i 1 1 e that should be con- 
verted to a Stri ng (if necessary) and inserted at this point. 

V Lines 13, 15, and 17: Tell the Tiles framework that these are named inser- 
tion points for content that will be provided by a JSP page that uses the 
template. 

When you have defined the template, you can create JSP pages that will use 
the template to flesh out the page. Continuing with the preceding example, 
Listing 11-8 shows aloggedin.jsp page using Tiles and the template that 
we defined in Listing 11-7. This page has the same look and feel, content, and 
functionality as the page described in Listing 11-5, which uses i ncl udes. But 
notice the difference in size between Listing 11-8 and 11-5. 
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Listing 1 1 -8 loggedin.jsp Page Using Tiles 
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<%@ include f i 1 e=" tagl i bs . j sp" %> 



'es:insert page= ' mai nTempl ate . jsp ' f 1 ush= ' true ' > 

4 <tiles:put name="ti tl e" > 

5 <f mt : setBundl e basename="Appl i cati onResources" /> 

6 <fmt:message key=" 1 oggedi n . ti tl e" /> 

7 </tiles:put> 

8 <tiles:put name='logo' val ue= ' 1 ogo . jsp ' /> 

9 <tiles:put name='body' val ue= ' 1 oggedi nBody . jsp ' /> 

10 <tiles:put name= ' footer ' val ue= ' footer . jsp ' /> 
ll</ti 1 es : i nsert> 

This example uses the template (mai nTempl ate .jsp) that we defined in 
Listing 1 1-7 to provide the structure for the page. Note the following items in 
Listing 11-8: 

Line 3: The t i 1 e s : i n s e r t tag references the template with the page 
attribute. Everything in the body of the ti 1 es : i nsert tag is used to 
flesh out the template with content. 

Lines 4-7: Define an attribute whose name is "title" and whose value 
will be the result of evaluating the two tags (lines 5 and 6) in the 
ti 1 es : put body. As with other similar examples in this book, you will 
end up with a message string. 

Lines 8-10: Define the content to associate with the "logo", "body", 
and "footer" attributes, respectively. This content will replace the cor- 
responding ti 1 es : i nsert tags in the template. With the exception of 
1 oggedi nBody .jsp, the JSP files are the same ones (Listings 11-3 and 
11-4) defined in the preceding section. The 1 oggedi nBody . j sp of 
Listing 11-6 consists of the specific body content found in the example 
in Listing 1 1-5. 

In Figure 1 1-2 we represent graphically how this process might work when 
considering multiple presentation pages using one template and sharing vari- 
ous tiles. 



The beauty of the Tiles approach is in the following benefits: 

u* Guaranteed consistency in the look-and-feel of the Web application: 

Because all pages in the site get their structure from one template or 
another, the page appearance is consistent with the appearance defined 
in the template. Changing the look-and-feel is as simple as modifying the 
underlying template file. 

Ease of maintenance: Changing the content is also easy. Modifying a tile 
used everywhere (such as f ooter . j sp) pushes those changes to all 
pages that reference the tile. Changing the content used by only one 
page (for example 1 oggedi nBody . j sp) is also easier because that infor- 
mation is isolated from other content. 
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Figure 11-2: 

Diagram 
showing 
page 
composition 
using the 
Tile 

framework. 



Template 



layout.jsp 
{used by 3 
pages) 



JSP Pages 



home.jsp 



v \ 



jom.jsp 



\ 

J7 v 



album.jsp / I 

A 

A 



Tiles 




footer.jsp 

(used in 3 pages) 






* homeContent.jsp 
(used in 1 page) 






joinContent.j 
(used in 1 pe 


sp 

ge) 

r 






albumContent.jsp 
(used in 1 page) 

M 



Configuring Tiles 

You need to attend to a few configuration issues to use the Tiles framework 
with Struts. The Tiles library is already included in the Struts framework, so 
that is one less thing to worry about. But you do need to perform the follow- 
ing steps: 

1. Put the tiles TLD file (struts ti 1 es . tl d) in with all the other TLD 
files, usually in the W EB I N F folder. 
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You can find this file in the ti 1 es- documentation .war file that comes 
with the Struts 1.1 distribution. 

ate the web .xml file to include a reference to the strut stiles, 
file. 

Here's an example of what a reference might look like: 

<taglib> 

<tagl ib-uri>/WEB-INF/struts-ti 1 es . tl d</tagl i b-uri > 
<tagl ib-1 oca tion>/WEB- INF/struts -ti les .tl d</tagl i b- 
1 ocati on> 

</tagl ib> 

3. Include a tiles tagl i b reference in any page that uses Tiles tags. 

One thing that you may have noticed is that this technique requires two pages 
for each presentation page in the application. One page is the page definition 
(such as logged i n . j s p) and the other is the unique content (such as logged 
i nBody . j sp). This can be an added maintenance issue with large sites. Fortu- 
nately, the Tiles framework has a solution called definitions, which allow you to 
specify all the attributes that go to make up a Tile in a reusable structure. 
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Tiles definitions 

A Tile definition page is remarkably similar in structure to a root Tile page. The 
principle difference is the use of the ti 1 es : def i ni ti on tag instead of the 
tile: i nsert tag. Listing 11-9 shows an example of a definition in a JSP page. 



Listing 11-9 Tile Definition Using JSP 



1 <%@ include f i 1 e=" tagl i bs . j sp" %> 

2 

3 <ti 1 es : def i ni ti on i d=" 1 oggedi n" page= ' mai nTempl ate . jsp ' > 

4 <tiles:put name="ti tl e" > 

5 <f mt : setBundl e basename="Appl i cati onResources" /> 

6 <fmt :message key=" 1 oggedi n . ti tl e" /> 

7 </tiles:put> 

8 <tiles:put name='logo' val ue= ' 1 ogo . jsp ' /> 

9 <tiles:put name='body' val ue= ' 1 oggedi nBody . jsp ' /> 

10 <tiles:put name= ' footer ' val ue= ' footer . jsp ' /> 



ll</ti 1 es : def i ni ti on> 



The definition is mostly the same as the Tile defined in Listing 1 1-8. The only 
difference is in line 3. In Listing 11-9, line 3 contains the ti les : def i ni ti on 
tag along with one attribute named i d. The i d attribute enables you to refer- 
ence the definition in other places. After the Tiles framework processes a def- 
inition, the definition is placed into the page scope (different scopes can be 
specified) as a JavaBean. From there, other pages can use the definition with 
the ti les : insert tag. 
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Here is an example of using the bean for creating a Tile: 

:insert beanName=" 1 oggedi n" flush="true" /> 



result is a page that's identical to the page from Listing 11-8. That is well 
and good if you want to create a 1 oggedi n page, but what if you want to use 
different content for the title and body? No problem. You simply override the 
default puts with new ones. For example: 

<ti 1 es : i nsert beanName=" 1 oggedi n" flush="true" > 
<tiles:put name="title> 

<fmt : setBundl e basename=" Appl icationResources" /> 

<fmt : mess age key="musi cl i st . tit! e"/> 
</ti 1 es : put> 

<tiles:put name= ' body ' va 1 ue= ' musi cLi stBody . j sp ' /> 
</ti 1 es : i nsert> 



This example replaces the definition's puts for the title and body with ones 
more appropriate for the desired page. 

You can also create definitions that inherit from another definition. This 
makes reuse of definitions a reality. Listing 1 1-10 is an example of creating a 
root definition named "main" and a child definition named " 1 o g g e d i n " . The 
" 1 oggedi n " definition inherits all the properties that belong to "main " and 
extends it by adding two additional properties, "title" and "body". 



Listing 11-10 Tile Definition Using JSP with Example of Inheritance 

I <7o@ include f i 1 e=" tagl i bs . j sp" %> 
2 

3 <ti 1 es : def i ni ti on id="main" page= ' mai nTempl ate. jsp' > 

4 <tiles:put name='logo' val ue= ' 1 ogo . jsp ' /> 

5 <tiles:put name= ' footer ' val ue= ' footer . jsp ' /> 

6 </ti 1 es : def i ni ti on> 

7 <ti 1 es : def i ni ti on name="l oggedi n" extends="mai n " > 

8 <tiles:put name="ti tl e" > 

9 <fmt : setBundl e basename="Appl i cati onResources" /> 

10 <fmt:message key=" 1 oggedi n . ti tl e" /> 

II </tiles:put> 

12 <tiles:put name='body' val ue= ' 1 oggedi nBody . jsp ' /> 
13</tiles:definition> 

Admittedly, using a JSP page to create definitions is a bit awkward, and it 
doesn't really address the issue of reuse very well. You could put all the Tile 
definitions into a single JSP file (much like we did with tag library definitions) 
and include the JSP file for each Tile that you want to create using definitions. 
This works but is inefficient, because each time you load a page, the loading 
mechanism recreates the definitions. A better method is to use an XML docu- 
ment to create the definitions and then load and build them when the Web 
application starts. 
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Using XML for Tile definitions 



( ax for creating a definition in XML and in JSP is remarkably similar, 
pie, Listing 11-11 duplicates the definitions shown in Listing 11-9 
using JSP. 



Listing 11-11 Tile Definition Using an XML Configuration File Named 
tileDefinitions.xml 



<?xml versi on=" 1 . 0" encoding="IS0-8859-l" ?> 

<!D0CTYPE tiles-definitions PUBLIC 

"-//Apache Software Foundati on//DTD Tiles Configuration 
1.1//EN" 

" http : // Jakarta. apache. org/struts/dtds/ti 1 es - 
conf ig_l_l . dtd"> 
<ti 1 es-def i ni ti ons> 

<!-- main definition --> 

definition name="main " path=" /mai nTempl ate . jsp"> 
<put name=" 1 ogo" val ue=" 1 ogo . jsp" /> 
<put name="f ooter" val ue="f ooter . jsp" /> 

</def i ni ti on> 



<!-- loggedin definition --> 

definition name=" 1 oggedi n" extends="mai n"> 

<put name="title" val ue=" 1 oggedi nTi tl e . jsp" /> 
<put name="body" val ue=" 1 oggedi nBody . jsp" /> 

</def i ni ti on> 



</tiles-definitions> 



Besides the small syntax changes and the use of a slash (f) in front of the path, 
we had to write another small JSP page to get the proper title information, as 
shown in Listing 11-12. You can't know what the proper title string should be 
in the XML file because the string is Locale dependent. 



Listing 11-12 Defining the Title, loggedinTitle.jsp 

<%@ include f i 1 e = "tagl i bs . jsp" %> 

<fmt : setBundl e basename="Appl i cati onResources " /> 

<fmt : mess age key = " 1 oggedi n . ti tl e" /> 

To make use of the Tiles configuration file, you need to adjust the Struts con- 
figuration a little bit by adding a new plug-in. The Ti 1 esPl ugi n processes 
definitions in a centralized file. In its simplest form, the Ti 1 esPl ugi n takes 
no parameters. The plug-in assumes that the Tiles configuration XML file is 
named "ti 1 eDef i ni ti ons . xml ". Here is the line to add to the struts - 
conf i g . xml file: 
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<plug-in className= "org. apache. struts. tiles. TilesPlugin" /> 
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decide to use XML Tiles definitions, you also commit to using the 
iles version of the RequestProcessor class, Ti 1 esRequest 
Processor. You don't have to do anything more — the plug-in takes care of 
everything. However, if you've already replaced RequestProcessor with 
your own custom class , your class needs to extend TilesRequestProcessor 
instead of RequestProcessor. 

The final step in this process that makes it all worthwhile is changing the 
forwards in the actions in struts -conf i g . xml . Normally, f orwa rds refer to 
a destination JSP file where control will be forwarded to when an action has 
completed. However, now we can specify also a definition of where control 
should be forwarded to. For example, instead of the normal success forward 
in our Logi n action, you use this: 



<forward name="success" p a t h = " 1 oggedi n"/> 



The path is the name of the Tile definition where control should be forwarded. 

To summarize, to use Tile definitions in an XML format, you should do the 
following: 

1. Create your definitions in ti 1 eDef i ni ti ons . xml . 

This file should be in the WEB - 1 N F folder. Other names for the file could 
be used, but you must notify the system of those names when defining 

Ti 1 esPl ugi n. 

2. Add the Ti 1 esPl ugi n class as a plug-in to the struts conf i g. xml file. 

Remember that if you've already defined a custom RequestProcessor, 
the custom class must extend TilesRequestProcessor instead of 
RequestProcessor. 

3. For each forward element that you want to forward to a Tiles defini- 
tion, modify the path to refer to the definition ID. 

Using Tile definitions allow you to eliminate the need for a presentation JSP 
page, such as 1 oggedi n . jsp. Instead you can use an XML Tile definition as a 
replacement. 

We've just covered the basics of the Tiles framework. This framework offers a 
robust and comprehensive solution to enforcing consistency and reducing 
maintenance for Struts applications. If you're interested in further details, 
look at the references found at the bottom of the Tiles documentation page 
on the Struts Web site: 



Jakarta. apache. org/struts/userGui de/dev_ti 1 es . html 
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In This Chapter 

Making your application responsible for security 
Handing over security responsibility to the container 



1 

m f you're developing an application that has any pages or other resources 
«C that need restricted access, you need to decide on how to approach the 
issue of security. You can take one of two broad approaches to managing 
security in a Web application. You can make the application responsible for 
its own security issues or leave security issues to the Web container. As you 
see in the following sections, both approaches have their advantages and 
disadvantages. 

In the issue of security, you need to be concerned with two matters: 

Limiting access to a certain subset of users: When users make a request 
and are granted permission to see the page or perform the operation, we 
say that they're authorized. 

Making sure users are who they say they are: When users have been ver- 
ified to be who they say they are, we say that they've been authenticated. 

Therefore, the two issues of security are authorization and authentication. 



Making the Application Responsible 

When the application is responsible for its own security, it must ensure that 
the user has been authenticated and is authorized to view the page or perform 
the action before allowing access to that page or operation. The application 
can respond in one of the following ways: 

v 0 If the user is authenticated but not authorized, the application denies 
access to the user and forwards the user to a "You can't do that" page. 

I ^ If the user has not yet been authenticated, the application forwards the 
user to a login page. 
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Logging in and authenticating a user 

jser requests or is referred to a login page, he or she enters the 
iate username and password for the Web site. When the user submits 
the form, the application uses the values in the username and password fields 
to authenticate the user by testing the values against a list of valid username 
and passwords. This list could be in memory, in an SQL database, in an LDAP 
(Lightweight Directory Access Protocol) server, or just about anywhere else 
on the network you could think of. 

When the application has authenticated the user, the authentication informa- 
tion is typically stored somewhere (usually in the session). Then the next time 
the user requests a protected page, the security mechanism can first check to 
see whether the user has already been authenticated. If so, the application 
processes the requested page. Otherwise, the application forwards the user 
to the login page. 
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Authorizing a user 

After authentication, the next task is authorization. In many Web applications, 
authentication and authorization may be the same — pages and operations 
are open to all authenticated users. After authentication is complete, further 
authorization is unnecessary. 

However, if you have many levels or classes of users, each of whom can view 
different pages or perform different operations, you need an authorization 
procedure when those requests come up. 



Authentication and authorization in Struts 

You need to perform authentication and authorization checks, each time a 
user requests a protected page or operation. What is an effective way to 
manage these checks in a Struts application? 



One approach is to insert an authentication check at the beginning of any 
Acti on class that you need to protect. Here is a code segment that shows 
how you can perform this check: 



1 


HttpSession session 


= request . getSessi on () ; 


2 


User user = (User) 


session . get Attn' bute( "user " ) ; 




// ensure that user 


has been authenticated 


3 


i f ( user == null) 
{ 




4 


return (mapping 

) 


. fi nd Forward (" 1 ogi n" )) ; 
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When a user is authenticated, a User object representing the user is placed 
in the user's session with the key, " u s e r " . In this way, whenever you need to 
ser's authentication, you just need to get the User object out of the 
ines 1 & 2). If the User object is available (Line 3), you can assume 
that the user was previously authenticated. If the User object is not available 
(Line 3), you know that the user needs to be authenticated and can forward 
him or her to the login page (Line 4). 



Authorization, if necessary, requires that you consider the permissions that 
have been granted to the user in relation to the requested page or operation. 
This means that before performing an operation, the code must check to see 
whether the current user is authorized to perform that operation. 

One approach is to encapsulate the permissions granted to the user into 
the User object created at login time. These could take the form of boolean 
values for the possible permissions. For example, you could have a Web 
application that has three levels of users, each of which is allowed to view 
different pages in the application. Besides the standard user, suppose that 
you have department head users and administrative users. Therefore, you 
can have two boolean properties in the User object that indicate this, 
departmentHead and admi ni strator. You can reference them with the 
methods i sDepartmentHead and i sAdmi ni strator. 

Now when you want to check the authorization level of the user before dis- 
playing a page, you can do something like the following in the Acti on class: 

1 HttpSession session = request . getSessi on () ; 

2 User user = (User) sessi on . getAttri bute ( "user" ) ; 
// authenticate the user 



// ensure that user is an administrator authorized 

// to perform this operation 

3 if ( ! user . i sAdmi ni strator( ) ) 
{ 

4 return (mappi ng . f i ndForward ( "unauthori zed" ) ) ; 
) 

// begin modification of logins 



This is a reasonable approach if you have a small Web application that's not 
going to get much bigger. If the application does become much larger, how- 
ever, the drawbacks are considerable because you have authorization code 
interspersed throughout many Acti on classes. 



Customizing the RequestProcessor Class 

For larger Web applications, another approach is to centralize the authentica- 
tion process in one class. 
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The RequestProcessor class is one of the key classes in the Controller layer. 
(For more information about the RequestProcessor class, see "Processing 

in Chapter 4.) This class handles all requests for the Struts applica- 
)is therefore an ideal location to place an authentication function. 
The Struts developers must have had this use in mind when they added an 
extension point (a dummy method made to be overridden in a subclass) to 
the class. 



The RequestProcessor class has a method named processPreprocess 
that does nothing in the class (other than return true) and exists only to be 
overridden by you. Here is the method signature: 

protected boolean processPreprocess(HttpServletRequest request, 

HttpServletResponse response) 



Each time RequestProcessor processes a request, it calls the process 
Preprocess method. Normally, nothing happens. However, here is an ideal 
place to add any kind of preprocessing actions that you would like to occur 
for each request — such as authentication. 



Listing 12-1 shows how you might extend the RequestProcessor class and 
override the processPreprocess method to include authentication. We sub- 
class the RequestProcessor class to create CustomRequestProcessor. 



Listing 1 2-1 Overriding the processPreprocess Method of the 
CustomRequestProcessor Class 

1 protected boolean processPreprocess(HttpServletRequest request, 

HttpServletResponse response) 

2 I 

3 boolean conti nueProcessi ng = true; // assume success 

4 // Test if the request is a login request 

5 try 

6 I 

7 HttpSession session = null; 

8 // ensure that the user's session has not timed out 

9 i f ( request . i sRequestedSessi onldVal id( ) ) 

10 session = request. getSessiont ) ; 

11 else // user's session has timed out, make them login again 

12 response. sendRedi rect("login.jsp"); 

13 // get the current request's path 

14 String path = processPath( request , response); 

15 // don't do any testing if user is logging on 

16 if ( !path.equals((String) "/login")) 

17 ( 

18 // get the user bean 

19 User user = (User) sessi on . getAttri bute( "user" ) ; 

20 // ensure that user has logged on 

21 if (user == null) // else make them login first 

22 { 
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23 try 
( 

response. sendRedi rect("login.jsp"); 

) 

catch( Excepti on ioe) 

28 { 

29 log.errorCproblem redirecting in processPreprocess - " + 

i oe . getMessage( ) ) ; 

30 ) 

31 continueProcessing = false; 

32 ) 

33 ] 

34 ) 

35 catcht Excepti on ioe) 

36 { 

37 log.errorCproblem processing path - " + i oe.getMessage( ) ) ; 

38 continueProcessing = false; 

39 ) 

40 return continueProcessing; 
411 



Here's how this code works: 



Line 9: The overridden processPreprocess method first makes sure 
that the user's session has not timed out and is still valid. 

i>* Line 12: If the session has timed out, the user is redirected to the 
1 o g i n . j s p page to log on again. 

Line 14: We get the current request path to determine whether the user 
may be trying to log on right now. The processPath method is inherited 
from the superclass RequestProcessor. If the user is trying to log on, 
we skip all the authentication code in Lines 16-33 and just let the request 
go through. 

*** Lines 19 and 21: If the request is anything other than the login page, we 
ensure that we have a User object before continuing. 

*«* Line 25: If we do not have a user object, the user has not yet logged on, 
so we redirect the user to the 1 ogi n . j sp page. 

Every request handled by Struts executes this code. The approach used in 
Listing 12-1 may not be an appropriate solution if you have a mixture of pro- 
tected and unprotected pages handled by Struts, because in that case you 
need to disregard requests for unprotected pages. If you have HTML pages or 
non-Struts JSP pages that need protection, this approach will not work because 
it handles only requests that come through the Struts controller. Furthermore, 
this approach does not address the issue of authorization specific to particular 
lines of code in the Acti on class. 
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The final step is to inform Struts of the new RequestProcessor by adding it 
to the struts conf i g . xml file, as shown here. 

======= Controller Definition =========================== --> 

ler processorCl ass="dummi es . struts. CustomRequestProcessor" /> 

The controller definition comes right after the action-mappings definition in 
the configuration file. 



Declaring Security in 
l/our Web Container 

The J2EE specification defines a declarative security mechanism in which 
application security is expressed in a declarative syntax in the configuration 
files. Using declarative security, Web containers can provide both authentica- 
tion and authorization services for Web applications running in the Web con- 
tainer. You can use these services with Struts applications. 

Four basic steps need to happen for the container's declarative security to 
work. We discuss each of these steps in detail in this section. 



Step 1 — Setting up the rotes 

The first step is to define the roles that your application will use. Roles are a 
way of grouping users. A role represents a set of permissions that you want to 
apply to a certain group of users. For example, a purchasing Web application 
might have three categories of users: Regular users create purchase orders, 
department heads approve purchase orders, and administrators add and 
delete users from the system. Regular users and department heads should not 
be able to add or remove users. Regular users and administrators should not 
be able to approve purchase orders. To accommodate these three types of 
users, you might define a role for each group of users — standard, depthead, 
and admi n. 



Step 2 — Defining the realms 

The second step is to define a realm in the Web container's server . xml file. 
A realm identifies a set of users, their passwords, and their associated roles. 
Four types of realms are possible, depending on how you set up your user 
information: 
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UserDatabaseRealm: The simplest but least flexible and secure choice. 
In this scenario, usernames, passwords, and roles are kept in a static file 
is loaded into the Web container's memory at startup. For Tomcat, 
file defaults to tomcat-users . xml . 



i>* JDBCRealm: If you keep your username, passwords, and roles in an SQL 
or other database, using JDBCReal m makes sense. You must have two 
tables for user information: one for usernames and passwords and the 
other for the associated roles given to users. 

JNDIRealm: Use this realm if you use an LDAP (Lightweight Directory 
Access Protocol) server. JNDI (Java Naming and Directory Interface) is 
the standard for Java access to LDAP servers. JNDIRealm gives you all the 
options you need to look up usernames, passwords, and roles from the 
LDAP server. 

JAASRealm: JAAS (Java Authentication and Authorization Service) pro- 
vides an implementation of the PAM (Pluggable Authentication Module) 
framework that allows applications to remain independent of the 
authentication and authorization implementation. You can find this ser- 
vice in J2EE SDK 1.4 and above. 



Suppose that you have a database that contains all your users, their login 
names, and their passwords. Because JDBCReal m covers this type of data- 
base, you would choose JDBCReal m in the server . xml file. To accommodate 
the roles, you need to create a new database table to hold the same login 
names and their associated roles. If a user has more than one role, you need 
one row containing the user name and role for each role. The table structures 
would look like Figure 12-1. 



userRoles 



Figure 12-1: 

Table 
structures 
for users 
and roles. 



user_name, varchar 25 



user_pass, varchar 10 



userjogons, int 



user_name, varchar 25 



user role, varchar 15 



Here are some example rows of data for each table: 

users table userRoles table 

user_name user_pass user_name role_name 

bjohnson indigo bjohnson admin 

clrook lucy!2$ clrook depthead 
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After you defined and populated the tables, you need to define J DBCRea 1 m 

for the database you're using in the server, xml file. The server, xm 1 file 
■alifeadifc^ias definitions (commented out) for several of the most common 
jjap^^^s — MySQL, Oracle, and the generic database connected with ODBC. 

In Listing 12-2, we modify the sample JDBCRealm definition for MySQL and 

put it into use. 



Listing 12-2 JDBCRealm Definition for MySQL in server.xml 

1 <Realm cl assName="org . apache . catal i na . real m. JDBCReal m" 



2 debug="99" 

3 driverName="com.mysql . jdbc . Dri ver" 

4 connecti onUR L=" jdbc: my sql ://localhost/Purchasing" 

5 connecti onName = " we bpurchasing" 

6 connecti onPassword="bigmoma2" 

7 userTabl e="users" 

8 userNameCol="user_name" 

9 userCredCol="user_pass" 

10 userRol eTabl e="userRol es" 



rol eNameCol =" rol e_name" /> 

Note the following lines from Listing 12-2: 

Line 1: Specifies the fully qualified class name of the realm that we're 
defining — in this case, JDBCRea 1 m. 

Line 2: Sets the debug level to the lowest possible setting. 

u 0 Lines 3 and 4: Specify the database driver and connection URL, 
respectively. 

\^ Lines 5 and 6: Specify the username and password used to connect to 
the database. 

u 0 Line 7: Names the table that contains the username and password 
information. 

v 0 Lines 8 and 9: Name the username and password column names. 

V Line 10: Names the table that contains the user roles. 

Line 11: Names the column that contains the role. The column in this 
table that contains the username must have the same name as the 
column that contains the username in the user table. In this case, the 
column in this table that contains the username is named "user_name". 



All of these definitions let the container know how to access the user and role 
information for authentication and authorization. Because the container is 
managing security and we are using the J DBCRea 1 m, the database driver must 
be available. Therefore, the driver should be placed somewhere on the con- 
tainer's classpath. For Tomcat, place the driver in the common /l i b folder. 
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You can define only one realm for the Web container. Every application that 
uses container-based security must use that same realm. 

oks 

Step 3 — Specifying authorization areas 

The third step in the process is to declare the areas in the application that 
you want to protect by modifying the application's web . xml file. When using 
Struts applications, you can make these declarations in two areas: in the 
struts-config.xml file to protect Struts actions and in the w e b . xm 1 file to 
protect other resources, such as JSP, HTML, and image files. 



Struts use of user rotes for authorization 

You can protect a Struts Act i on in the container-based security scheme 
using the rol es attribute in the acti on tag. RequestProcessor always 
checks to see whether an Acti on is protected with a role. If it is protected, 
RequestProcessor checks to make sure that the user's role matches one of 
the permitted roles before Acti on is called. Note that you do not have to 
subclass RequestProcessor using this security approach. 

Here is a code snippet from astrutsconfig.xml file: 

<action path=" /acctl i st" 

ty pe= " com. othenos. purchasing. struts. AcctListAct ion" 
name = "acctl_i stForm" 
scope="sessi on" 
i nput=" /acctl i st . jsp" 
roles="admin,deptnead"> 
<forward name="errors" path = "/acctl ist. jsp"/> 
<forward name="success" path = " /acctl i st . j sp" /> 
</acti on> 



Note the rol es attribute in the acti on definition. This attribute specifies 
that only users who have either admin ordepthead roles may execute this 

acti on. 



General-purpose authorization 

Use the web . xml file to protect all the other resources that you can't protect 
with struts-conf i g. The purpose of the securi ty-constrai nt tag is to 
define an area in the Web application that should be protected from general 
use. The syntax for the security- constraint tag follows: 

< ! ELEMENT security-constraint (display-name?, web-resource-collection+, 

auth-constraint?, user-data-constraint? )> 
<! ELEMENT display-name (#PCDATA)> 

< ! ELEMENT web-resource-collection (web-resource-name, description?, url- 
pattern*, 

http-method*)> 
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< ' ELEMEN" 
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< ! ELEMEN" 



< ! ELEMENT web-resource-name (#PCDATA)> 

<J ELEMENT description (#PCDATA}> 

T url -pattern (#PCDATA)> 

T http-method (#PCDATA)> 

T auth-constrai nt (description?, role-name*)> 

<! ELEMENT description (#PCDATA)> 

< ! ELEMENT role-name (#PCDATA}> 

< ! ELEMENT user-data-constraint (description?, transport-guarantee)) 

< ! ELEMENT description (#PCDATA)> 

< ! ELEMENT transport-guarantee (#PCDATA)> 



The syntax is not quite as complex as it might first appear. Many of the elements 
are optional. For each area that you want to protect, you use a secu ri ty - 

constraint tag to define the area. For each security- constraint tag, you 
need at least one web-resource-col 1 ecti on tag that describes the area to 
be protected. 



i 



Suppose that you want to protect a folder (/ad mi n) that contains some 
JSP pages for use by users in only the admin role. It might look like this: 



<security -constraint) 






<web- resource -col 1 ecti on > 




<web-resource-name> 




Administrative Area 




</web-resource-name> 




<url -pattern) 
/admin/*, jsp 










</url -pattern) 






</web-resource-collection> 




<auth-constrai nt> 






<role-name>admin</role-name> 




</auth-constrai nt> 






</security -constraint) 







The sequence of tags in configuration files in important. Refer to Chapter 7 
for information on a particular tag. 

The web-resource-name tag is used only for identification for human read- 
ers. The url -pattern tag defines the context-relative portion of the URL that 
indicates a protected area. To protect all resources in the admi n folder, don't 
include .jsp. The auth-constrai nt/role- name tag defines which user 
roles may have access to these protected resources. 



To find out more about the security-constraint tag, browse or download 
the J2EE 1.4 Tutorial atjava.sun.com/j2ee/1.4/docs. 
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Step 4 — Defining authentication methods 



tep is defining the authentication mechanism to use. When a user 
a protected area, the container first determines whether the user 
has been authenticated. If not, the container performs authentication based 
on one of the four authentication methods selected. The four possible 
authentication methods are: 



BASIC: If you choose BAS I C authentication, the Web container uses the 
standard HTTP basic authentication. This means the Web browser asks 
the user for a username and a password. The password goes across the 
network in base64-encoded text. 

DIGEST: The DIGEST form of authentication uses a more robust encryp- 
tion method to send the passwords across the network. However, this 
form of authentication is more complex to set up and prone to problems 
with the current 4.x versions of Tomcat. 

FORM: In the FORM style of authentication, you provide both the login 
form and the error form (in case the login has problems). Unless you're 
using SSL (Secure Sockets Layer, that is, HTTPS), passwords go across 
the network unencrypted. 

i>* CLIENT-CERT: This form of authentication requires the use of SSL. 
During authentication, the browser is asked to present an X.509 client 
certificate in lieu of the user typing a username and password combina- 
tion. C L I E NT - C E RT is a complex topic, so we do not discuss it in detail. 
To read more about this and other forms of authentication, look at the 
J2EE tutorial atjava.sun.com/j2ee/1.4/docs. 

The web . xml file has a login-config tag that you use to define the authenti- 
cation method. Here is the syntax of the tag: 

< ! ELEMENT login-config (auth-method? , realm-name?, form-login-config?)> 
< ! ELEMENT auth-method (#PCDATA)> 
<! ELEMENT realm-name (#PCDATA)> 

< ! ELEMENT form- 1 ogi n-conf i g (form-login-page, form-error-page)> 
<! ELEMENT form-login-page (#PCDATA)> 
<! ELEMENT form-error-page (#PCDATA)> 

The auth -method tag refers to one of the four possible authentication meth- 
ods: BASIC, DIGEST, FORM, or CLI ENT-CERT. The realm- name tag is the name 
that will be displayed on the browser-supplied login form in BASIC or DIGEST 
forms of authentication. 



If you choose the FORM type of authentication, you also need to supply the 
forms to display using the f o r m - 1 o g i n - c o n f i g tag. Specify the login form to 
use with the form log in page tag. The error page should be defined in the 
form-error-page tag. Both the login and error pages are required if you use 
FORM based authentication. 
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3 B 0 Q$$$uthentication 



To integrate the information in this chapter, this section provides two exam- 
ples of authorization and authentication. 

Protecting the entire application With BASK authentication 

In the first example, we assume that every page of the application is protected 
from all users, except those who have the role of a dmi n . We use the BASIC 
form of authentication, letting the browser display the login form. Here is the 
code snippet from web . xml : 



<security-constraint> 








<web- resource -col 1 ecti on> 




<web-resource-name> 




Al 1 of Appl i cation 




</web-resource-name> 




<url -pattern> 








/* 








</url -pattern> 








</web-resource-collection> 




<auth-constrai nt> 








<rol e-name>admi n< 


/ 


"ol e-name> 




</auth-constrai nt> 








</security-constraint> 








<1 ogi n-conf i g> 








<auth-method>BASIC</a 


uth-method> 




<realm-name>Logi n Sam 


P 


e Appl i cati on</rea 1 m-name 


> 


</l ogi n-conf i g> 









The url - pattern tag specifies that all resources of the application should be 
protected. The use of the rol e-name tag with the a dmi n role specifies that 
only users with that role can access the pages. Figure 12-2 shows an example 
of a login form using BASIC authentication. Notice that the realm name is dis- 
played in the login form. 



Figure 12-2: 

BASIC 
authenti- 
cation login 
screen. 




Connect to loc.ilhost 



as 



Login Sample Application 
User name; | 



Password: 



Q Remember my password 
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Restricting access to Wo folders 

In this example, we assume that a group of pages in the admin folder should 
1 1T\ f\ ^"%eL^d^:ted from all except those with admin roles. In addition, a group of 

' >^ K-' >^ >*clo\kwig pages in the a cct folder should be restricted to those users with 
the depthead or admi n role. Again, we use the BASIC form of authentication, 
letting the browser display the login form. Here is the code snippet from 
web . xml : 

<!--Security for Administrative pages --> 
<security -constraint) 

<web- resource -col 1 ecti on> 
<web-resource-name> 

Admi ni strati on 
</web-resource-name> 
<url -pattern) 

/admi n/* 
</url -pattern) 
</web-resource-collection> 
<auth-constrai nt> 

<role-name>admin</role-name> 
</auth-constrai nt> 
</security -constraint) 

<!--Security for Accounting pages --> 
<security -constraint) 

<web- resource -col 1 ecti on > 
<web-resource-name> 

Accounti ng 
</web-resource-name> 
<url -pattern) 

/acct/* 
</url -pattern) 
</web-resource-collection> 
<auth-constrai nt> 

<role-name>depthead</role-name> 
<role-name>admin</role-name> 
</auth-constrai nt> 
</security -constraint) 

<!-- Authorization BASIC --> 

<1 ogi n-conf i g> 

<auth-method>BASIC</auth-method> 
<realm-name>Logi n Sample Appl i cati on</rea 1 m-name> 

</l ogi n-conf i g> 

The two secure areas are constrained so that only users with the proper roles 
can view them. One interesting thing to note is that we can switch realms in 
the server. xml file without having to change any settings in the we b . xm 1 
file. So you could initially use UserDatabaseRea 1 m and then change to 
JDBCReal m with no side effects on the security configuration in web . xml . 
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The steps in setting up container-based, declarative security can be summa- 
rized in these four steps: 

de on the roles in which to group users based on the pages and 
)ns each group should be able to access or perform. 

2. Determine the authentication method to use — define the realm in the 
server . xml file. Make sure the appropriate user data is configured in 
the data source you are using. 

3. Define the authorization areas in the application by configuring the 
struts confi g . xml file. To define authorization on non-Struts 
resources, such as HTML files, use the web . xml file. 

4. Set up the authentication method for the application in the web . xml file. 
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In this part . . . 

7 his is where we put together all the knowledge in the 
book into an example Web application. In Chapter 13, 
we explain the tools in Struts for creating a log that you 
can use to troubleshoot problems. (Of course, you never 
have any problems, right?) In Chapter 14, we explain the 
code that you need to create MusicCollection.com, an 
application that lets users create, store, and edit a list of 
their favorite albums online. Users need to register the 
first time they visit the site and log on for subsequent 
visits. Then they retrieve their list of albums from the 
database and add, edit, or delete entries. When they are 
finished, they can log off. After completing this applica- 
tion, you should be off and running, creating your own 
Web applications. 
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.ogging Your Actions 



In This Chapter 

Advantages of logging 
Working with Commons logging 
Trying out Java 1.4 logging 
Getting familiar with Log4J 



■ M /hen an application is running, many events occur that would be valu- 
ww able for you to know about. Some events might be in the area of secu- 
rity, such as knowing when and how frequently users log on and off. You might 
also want to know when error conditions occur. The benefits of logging are 
limited only by the creativity and imagination of the developer. 

One way to track all this information is to write messages about the events in 
a place where you can look at them. Writing these messages on the system 
console, on a file on disk, in an e-mail message, or just about any place you 
can think of — is defined as logging the messages. 



Loqqinq (or Everyone 

Logging has been described as a low-tech debugging mechanism. That may 
be true, but logging can also be much more. Using logging, the developer can 
do the following, all without changing code: 

Provide useful information about the runtime state of the application 
Increase or decrease the amount of logging detail provided 
f Vary the format of the logging information 
*** Send the logging information to a different destination 

Create multiple logs 
V Turn logging on or off 
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ly, Struts provides the developer with a lot of flexibility when it 
comes to logging through the inclusion of the Commons Logging library — 
another of the many Jakarta projects — in the Struts library files. 

Commons Logging is a lightweight framework that provides a common log- 
ging interface to any one of the many actual logging packages, such as Log4J 
and Java 1.4. This common interface enables you, the developer, to pick and 
choose the logging package that you want to use without having to worry 
about changing your code. 

To use Commons Logging, make sure that the commons - 1 oggi ng. jar file is 
in your WEB- INF/1 ib directory. Import the Log and LogFactory classes in 
the source files that you want to include logging using the following: 

import org. apache. commons. logging. Log; 
import org. apache. commons. logging. LogFactory; 

The two classes of interest in the Commons Logging package are the Log 
class, which performs the logging function, and the LogFactory class, which 
knows how to get an instance of the Log class. After you import the two log- 
ging classes, you need to get an instance of a Log from the LogFactory by 
passing the Class that is invoking the logger, using the following: 



Log log = LogFac 


tory . getL 


og( Logi n . cl ass ) ; 





The LogFactory determines what type of logger to get based on the follow- 
ing steps: 



1. Look for an attribute named org .apache . commons . 1 oggi ng . Log in the 
common 1 oggi ng . properti es file. If the attribute exists, use the associ- 
ated value to choose the logger class. Otherwise, go to the next step. In 
this way you can explicitly define which logger implementation to use. For 
Log4J, use org. apache .commons .logging.impl .Log4JLogger. If you 
want the Java 1.4 logger, use the org. apache, commons . 1 oggi ng . i mpl . 
Jdkl4Logger class. 

2. Look for a system property named org. apache .commons .logging. Log. 
If the property is found, use the associated value to choose the logging 
implementation; the value should be one of the logger classes listed in 
Step 1. Otherwise, go to the next step. 

3. If the Log4J logging system is available inclasspath, use the corre- 
sponding Log4J Logger wrapper class. Otherwise, go to the next step. 

4. If the application is running with JDK 1.4 or above, use the correspond- 
ing Jdkl4Logger wrapper class. Otherwise, go to the next step. 
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Use the simple built-in logger called SimpleLog. SimpleLog sends all 
messages to System . err. You can configure this logger by setting vari- 
system properties. See the org . apache . commons . 1 oggi ng . impl . 
1 eLog API documentation for further details. You may find the API 
documentation for the Commons Logging package at Jakarta. apache, 
org /commons /l oggi ng/api/index. html. 



You use the log instance to write messages to the log file. The messages are 
written based on the priority of the message. Following are the possible pri- 
orities from most severe to least severe: 

v" Fatal: Severe errors that cause termination of the application 

Error: Other runtime errors or unexpected conditions 

Warn: Use of deprecated APIs, poor use of API, other errors or situa- 
tions that are unexpected but not necessarily wrong 

i>* Info: Interesting runtime events, such as initialization or shutdown actions 

Debug: Detailed information on the flow of events in the application 

Trace: More detailed information than the Debug level 



Each priority has a method by the same name with two different method sig- 
natures. For example, for the fatal priority, the methods are: 



1 og . fatal (Object message); 

1 og . fatal (Object message, Throwable t); 



Each of the other priorities has method signatures like fatal . The determina- 
tion whether or not to write the message to the log comes only when the 
method is called. The logger configuration specifies the lowest level of sever- 
ity to write out. For example, if you choose the WARN level, the log file will 
contain only log messages with priorities of FATAL, ERROR, and WARN. In this 
way, you have control over how much information you log. 

The ability to control the quality of logging information in the configuration 
file means that you can leave the logging code in the application without 
much of a performance effect. Only when you need more detailed information 
do you need to turn on the lower-level logging features. 

The one disadvantage of leaving the log statements in the code is that a cer- 
tain amount of overhead occurs when calling the methods even if the logging 
does not take place. To reduce that overhead, code guard methods are avail- 
able to test the logging level and skip the calling of logging methods if that 
level is not enabled. The code guard methods are 



1 ogl sFatal Enabl ed( ) 
1 ogl sErrorEnabl ed( ) 
1 ogl sWarnEnabl ed ( ) 
1 ogl slnf oEnabl ed ( ) 
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1 ogl sDebugEnabl ed( ) 
ljog!sTraceEnabled( ) 



is an example of using a code guard: 

if ( 1 ogl slnf oEnabl ed ( ) ) 
( 

1 og . i nf o ( "Starti ng mail server.") 

) 



Using JaVa 1.6 Lowing 

By default, the configuration file for Java 1.4 logging is logging. properties 
in the J RE / 1 i b directory. You can use an alternative means of reading the 
configuration file by specifying the file location and name in the j a v a . ut i 1 . 
logging.config.file system property. Look at the Java API documentation 
for the Java. lit il .logging.LogManager class for further information on 
logging configuration. 

You can set the following features in the configuration file: 

I f The priority level to log messages. INFO is the default. 

i>* The handler to use when logging. The standard is to log to the console. 
An optional handler is available to log to a file. Other handlers are avail- 
able to write to memory, an output stream, or a network stream. 

A SimpleFormatter or XML formatter. Use a formatter to format the log 
records. 



The Java 1.4 logging offers more features than the Simpl eLog implementa- 
tion in Commons Logging but fewer features than Log4J. 



Working With the LogbJ Package 

Log4J is a mature, industrial-strength logging package with a multitude of 
options. Chances are that this package will do everything you need and then 
some. Log4J is one of the many Jakarta open-source projects. 

The configuration file for the Log4J logging package is 1 og4 j . properti es. 
You usually place this file in the WEB-INF/classes folder. In addition, the 
Log4J library file, 1 og4 j . ja r, needs to be present in the WEBINF/lib folder. 
You may download the library file as well as sample configuration files from 
the Log4J Web site at 
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j a kart a. apache. org/log4j /docs/ index. html 
tation is also available at the site. 



Log4J offers more logging options than the Java 1.4 logger, including where 
you write the files and how you format them. Listing 13-1 shows a sample of a 
Log4J configuration file that outputs to the console and to a rolling log file. 



Listing 13-1 Sample Configuration File for Log4J 

1 # The root category uses two appenders called stdout and R. 

2 # The root category assumes the INFO priority for root. 

3 # If the priority is not specified, it is DEBUG. The root 

4 # category is the only category that has a default priority. 

5 log4j.rootCategory=INF0, stdout, R 

6 # stdout is set to be a ConsoleAppender which outputs to std out. 

7 1 og4 j . appender .stdout=org. apache . 1 og4j . ConsoleAppender 

8 § Configure stdout appender to use the PatternLayout 

9 log4j. appender. stdout.layout=org. apache. log4j. Pattern Layout 

10 # Pattern to output the caller's filename and line number 

11 log4j. appender. stdout. layout. conversi onPattern =%d ( DATE } %5p [%t] - 

%m%r\ 

12 # R is the Rol 1 i ngFi 1 eAppender that outputs to a rolling log 
§ file called rolling_log_file.log. 

13 1 og4 j .appender . R=org . apache. 1 og4 j .Dai lyRol 1 i ngFi 1 eAppender 

14 1 og4 j .appender . R. Fi 1 e=$ {catal i na . base) /l ogs/wp_l og_f i 1 e.l og 

15 log4j. appender. R. Da tePattern=' . 'yyyy-MM-dd' .txt' 

16 # Define a pattern layout for the file. 

17 # For more information on conversion characters (i.e. d,p,t,c,l ,m,n) 

18 # please see the PatternLayout class of the Log4j API. 

19 1 og4j .appender . R. 1 ayout=org . apache. 1 og4j . PatternLayout 

20 log4j. appender. R. layout. conversionPattern =%d { DATE ) Hp [Xt] (%F:%L) - Mn 

In Listing 13-1, note the following lines: 

V Line 5: Specifies the priority of IN FO using two appenders, stdout and R, 
which are defined later. 

Line 7: Specifies that Consol eAppender be used with stdout. This 
means all messages will be written to the system console. 

v 0 Lines 9 and 11: Specify the format to use when writing out messages to 

stdout. 
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v 0 Lines 13-15: Define the R appender as Dai lyRol 1 i ngLogAppender. This 
means that for each 24-hour period, a new file will be created and the 
pne closed. You specify the file name and location, as well as the 
jx that you want to append to the file after it has been rolled over. In 
this case, the suffix is the date followed by the . txt extension (such as 
2003-ll-27.txt). 

I Lines 19-20: Specify that the format for the R appender will be identical 
to the stdout appender. 

The configuration of Log4J offers many options. For detailed information on 
configuration issues, visit the Log4J Web site at Jakarta. apache. org/1 og4j/ 
docs and review the documentation. 
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In This Chapter 

Introducing the MusicCollection application 
Creating the database schema 
Configuring the data source 
Creating the pages 
Logging on 

Creating a user account 
Displaying albums 

Creating, editing, and deleting albums 
Logging off the program 
Handling exceptions in different ways 
Running the program 



7 his chapter shows you how to create a complete application using 
Jakarta Struts. To create this demonstration application, you need to 
apply most of the concepts and techniques we have explored throughout the 
book. You don't need to retype the code — you can find the complete code 
for the MusicCollection.com application at the Jakarta Struts For Dummies 
Web site at www .dummies. com/go/ Jakarta. 



Description of the Application 

The hypothetical MusicCollection.com application enables registered users 
to create and maintain a list of their favorite music. In the application, we call 
each listing an album. 
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The prospective user must join the Web site by entering a small amount 
of personal information, such as name, e-mail address, and a password. 
£nt visits to the site require users to log on using their e-mail 
nd password. 



After the user has logged on, the application retrieves a list of his or her 
albums from the database and displays this list. The user may modify or 
delete an album or create one. The application immediately updates all 
changes or additions in the database and displays the resulting album list. 



When finished, users may log off to remove their connection to the system. If 
an error should occur during the processing of a request, the application dis- 
plays an appropriate error page. 

Figure 14-1 shows the various pages and relationships that go to make up the 
application. 



C Start ) 



Figure 14-1: 

High-level 
view of the 
application's 
Web site. 



Cr 



Welcome 




Music List 





Delete Album 



Recoverable 
Error 



To maximize your exposure to the various capabilities and techniques dis- 
cussed throughout the book, we have made several design decisions about 
what should go into the application. These decisions are to 

v 0 Develop the pages with a common look-and-feel through the page com- 
position technique of using i ncl udes (Chapters 6 and 11) 

u* Use I18N throughout the application (Chapter 6) 

u* Maximize the use of the JSTL and Struts-EL tag libraries (Chapter 10) 

V Let Struts handle the creation ofActionForms by using its dynamic 
form capability (Chapter 6) 
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V Use the Validator plug-in to perform validation on the forms that need it 
(Chapter 9) 



a database to hold all application data (Chapter 5) 



Interact with the database using aDataSource managed by Struts 
(Chapter 5) 

Handle exceptions through the Struts declarative mechanism (Chapter 8) 

Write a custom ExceptionHandlerto provide better exception logging 
(Chapter 8) 

Provide a common authorization mechanism implemented in a cus- 
tomized RequestProcessor (Chapter 12) 

\S Perform initialization actions during application startup and cleanly 
close the DataSource before application shutdown by creating a 
custom plug-in (Chapter 9) 



Creating the database Schema 

One of the first steps in creating the application is defining the database 
scheme that you want to use. The primary purpose of the site is to manage 
lists of albums for individual users, so you can use one table for that pur- 
pose. We named the table a 1 bums. This table contains information about the 
albums, such as name, artist, year of release, type of media, and category of 
music. (You could add additional fields to the record structure if you want to 
track other types of data.) In addition, each database record has a unique ID, 
the user's ID, and the date and time of the record's creation. You see this 
table in Figure 14-2. 




Because this site is for only registered users, you need a table to keep track 
of those who have registered. We called the table users. The primary infor- 
mation consists of the first and last name of the user, e-mail address, and 
password. In addition, we want to keep track of how often users log on, the 
last time they logged on, when records were created, and the unique ID for 
each the user. Figure 14-3 shows the structure of the users table. 
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Configuring DataSource 

Because you're using a database to store user and album information, it makes 
sense to take advantage of the capability Struts has to manage DataSources, 
as discussed in Chapter 5. You may need to make slight modifications to the 
following configuration, depending on your database, driver, username, and 
password. Here is the definition of DataSource in the struts conf i g file for 
use with the MySQL database: 

<!-- ========== DataSource Definitions =================================== --> 

<data-sources> 

<data-source key="musi ccol 1 ecti on" 

type=" org. a pa che. commons. dbcp.BasicDataSource") 

<set-property property="descri pti on" value="Music Collection Database"/) 

<set-property property="dri verCl assName" val ue="com.mysql .jdbc. Driver"/) 

<set-property property="username" value="webuser"/) 

<set-property property="password" value="bigmoma"/) 

<set-property property="url " val ue=" jdbc:mysql ://localhost/musiccollection" /) 
<set-property property="maxCount" value="8"/) 
<set-property property="mi nCount" va 1 ue=" 2 " /> 
</data-source) 
</data-sources> 



Creating the Pages and Associated Files 

The application overview in Figure 14-1 shows that at least three pages have 
form data needing validation: Logi n, Join, and Al bum. As it turns out, the 
Musi cLi st page also needs a form, although validation is not necessary 

For those three pages using the form validation features of the Val i da tor 
plug-in, the dynamic forms will be of the DynaVal idatorForm class. The 
Musi cLi st dynamic form will be a DynaActi on Form class, because it doesn't 
need validation. 
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The Web site should have a similar look-and-feel on every page. To achieve 
that goal, you can use one of the page composition techniques that we dis- 
hapter 11. Instead of using the Tiles technology, we have elected to 
ncl udes technique to keep things simple. We will define common 
header and footer JSP files for each page of the Web site. 



We use an iterative development process to build the example application. 
You could take many approaches to construct the various components. 
However, we find it useful to start with one page and implement as many of 
the related parts as reasonable (for example, Acti on Forms, Actions, beans, 
and configurations). The general steps to do this follow: 



1. Define and create the page. 

Analyze the data needed for the page and create the JSP. All JSP pages 
should use the JSTL and Struts-EL tag libraries when needed. I18N 
should be included for every page. 

2. Configure the dynamic form, if necessary. 

If the page contains form fields, define the associated dynamic form in 
the struts config file. The dynamic form is either aDynaVal idator 
Form or a DynaActi onForm class, depending on whether or not field 
validation is needed. 

3. Add the validation rules to val i dati on .xml , if needed. 

If a dynamic form needs a field or fields to be validated, define the field 
validators in the va 1 i dati on . xml file. 

4. Create the Acti on class, if needed. 

All pages that need processing should have an Acti on class. Some 
pages may have two or more possible actions (for example, "new" and 
"update") that need to be handled in the Acti on class. 

5. Create the Bean class for the Acti on, if needed. 

Pages that interact with the Model layer need to have a bean whose 
responsibility is to encapsulate all the interactions with the database. 
In most cases, you also need to create a Data Transfer Object (DTO). 

6. Configure action mapping for the Acti on class, if needed. 

If an Acti on class is created, you need to define the action-mapping con- 
figuration in the struts config file. 

7. Repeat steps 1 through 6 for each page in the Web site. 

Let's begin by looking at each of the pages that make up the Web site, starting 
with the Home page. 
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page serves an entry point for both registered and prospective 
users. As such, this page provides a form for the user to log on as well as 
a mechanism for prospective users to create a user account. 

Because of the logon function, the Home page requires the following addi- 
tional components: 



v 0 A dynamic form for the logon fields 

Validation of the fields using the Validator plug-in 

h LoginAction class to process the logon 

i>* A LoginBean to interact with the database to authorize the user 

The use of a common authorization mechanism so that after the user is 
authorized, each page request easily verifies the user's status 



Home page design 

Let's sketch the content of the Home page to see what fields you need to 
include for user input. Clearly, you need to have fields available for the user 
to enter an e-mail address and a password. Furthermore, you need a button 
for the user to click to submit the information for logging on. 

However, if the user has not yet registered for the MusicCollection.com 
service, the user needs to fill out a registration form to get a user account. 
Although a different page (the Join page) will gather this information, the 
Home page needs a button for the user to click to indicate the desire to join 
MusicCollection.com. Clicking the button should take the user to the Join 
page. 

That is about all we need on the Login page. However, for eye appeal, you 
probably want to add some marketing text as well as images to the body of 
the page. 

Because this application uses the i ncl udes page composition technique, 
the main page (h ome . j s p) defines the structure of the page and includes the 
header, footer, and body information from other files. The header and footer 
are common to all pages and reside in the 1 ogo . jsp and footer . jsp files, 
respectively. The body of the page will go into a separate JSP page named 
home Content, jsp. We follow this convention in creating all JSP pages. 

Figure 14-4 shows how the Home page looks. 
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Figure 14-4: 

The Home 
page. 
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LoqinForm 

The next step is to define the dynamic form associated with the Login page. 
You define the dynamic 1 ogi n Form in the struts config file, as we explain 
in Chapters 6 and 9. The 1 ogi n Form has only two fields associated with it: 
the emai 1 and password fields. The following code segment is the definition 

for login Form: 



<form-bean name="loginForm" 

type=" org. apache. struts. val idator.DynaValidatorForm") 
<form-property name="emai 1 " 

type=" j ava . 1 ang . String" 
i n i t i a 1 = " " / > 
<form-property name="password" 

ty pe=" j ava . 1 ang . String" 
i n i t i a 1 = " " / > 

</form-bean> 



LoqmValidation and (/atidation.#mt 

You need to perform declarative validation on the two fields in 1 ogi n Form. 
The emai 1 field is required and should look like an e-mail address. The pass- 
word field is also required. In the val i dati on . xml file, you specify the val - 
i dators for the login Form as follows: 

<form name="loginForm"> 
<f i eld property="emai 1 " 

depends-" requi red .email "> 
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<argO key=" error .email . requi red"/> 
</field> 



Id property="password" 
depends="requi red") 
<argO key=" error . password. requi red"/> 

</field> 
</form> 



LoqinAction 

The basic idea behind Logi nActi on is to take the user's emai 1 and password 
values and give them to Logi n Bean for authorization. If authorization is suc- 
cessful, Logi nActi on saves the user information in the session and forwards 
control to the Musi cLi st page. If authorization fails, Logi nActi on creates an 
error message and returns control back to the Home page. 

Because the user can also request to sign up for an account, you should add 
another button for joining. This button is actually a Cancel button that, when 
clicked, submits the login form and puts an attribute (org. apache. struts, 
act ion. CANCEL) with a value of true into the request. Logi nActi on looks 
for this attribute-value pair. If Logi nActi on finds this pair, it forwards control 
to the j o i n . j s p page. 

You could put a link on the Home page instead of a Cancel button. However, 
using a link exposes the URL of the j o i n . j s p page to the public. Listing 14-1 
shows the body of the execute method of Logi nActi on. 



Listing 14-1 Body of the execute Method of LoginAction 

// did the user click the Join button? 
Boolean bCancel = 

(Bool ean) request .getAttribute( " org. apache. struts .act i on. CANCEL" ) ; 
i f ( bCancel != null ) 

i f (bCancel .bool eanVal ue( ) ) 

return (ma ppi ng.fi ndForwardt "joi n" )) ; 

// create a new LoginBean passing the datasource 

LoginBean lb = new LoginBean(getDataSource(request, "musi ccol 1 ecti on" ) ) ; 

// check to see if this user/password combination are valid 
// will return a non-null UserDTO if valid 

UserDTO user = 1 b. val idatellser( (Stri ng) ( (DynaVal idatorForm)form) . get ( "emai 1 " ) , 

(St r i ng) ( (DynaVal ida tor Form) form) . get ( "password" ) ) ; 

iftuser != null ) 
( 

// save UserDTO in session 

request . get Ses si on ( ) . setAttri bute( "user" , user ) ; 

return (ma ppi ng . f i ndForward( "success" ) ) ; 



Chapter 14: Creating the MusicCollection.com Application 



295 



DropBooEs 

Act ii 



// username/password not validated 



reate ActionError and save in the request 
AcTionErrors errors = new ActionErrors( ) ; 
ActionError error = new Acti onError( "error . 1 ogi n. i nval id" ) ; 
errors . add ( "login" .error) ; 
saveErrors(request, errors); 
return (mappi ng.fi ndForward( "fai 1 ure" ) ) ; 



LoqinBean, model layer, and 
exception handling 

The purpose of Logi nBean is to authorize the user. Therefore, when 
the Logi nBean is instantiated, a reference to DataSource is passed to 
Logi nBean. That reference is saved in an instance variable for use by the 

va 1 i dateUsermethod. 

To perform authorization, the va 1 i dateUsermethod must query the data- 
base's user table for a record that matches the given e-mail and password 
values. If the va 1 i dateUsermethod finds a record, it validates the user and 
returns a DTO for the user. The UserDTO is a class that holds user informa- 
tion in an object form, specifically the user's 1 name, f name, emai 1 , and i d. 
If the user is not found in the user table, a null value is returned, indicating 
authorization failure. 

Any exception that gets caught in the method is logged and, in turn, throws a 
ModuleException that is propagated up the calling stack until it reaches the 

ExceptionHandler for RequestProcessor. 

Listing 14-2 shows the val i dateUser method of Logi nBean. 



Listing 14-2 validateUser Method of LoginBean 

public UserDTO validateUser(String email, String password) throws 
Modul eExcepti on 

( 

UserDTO user = null; 
Connecti on con = null; 
Statement stmt = null; 
ResultSet rs = null ; 
String sQuery = " " ; 
try 
( 

con = dataSource.getConnection( ) ; 
stmt = con.createStatement( ) ; 

(continued) 
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sQuery = "SELECT * FROM Users " + "WHERE email = "' 
sQuery += email + + "AND password = "' + password + 
rs = stmt.executeQuery(sQuery) ; 
if (rs.nextO) 

// Create new user transfer object 
user = new UserDTCK ) ; 
user.setFi rstNamet rs . getStri ng( "fname" ) ) ; 
user.setLastName(rs.getString("lname")); 
user.setld(rs.getlnt("id")); 
user . setEmai 1 ( rs . getStri ng( "emai 1 " ) ) ; 



// update user login information 

sQuery = "UPDATE Users SET 1 astl ogi n=now( ) ,numlogins=numlogins+l 

where id=" 
sQuery += user . get Id ( ) ; 
int result - stmt.executeUpdate(sQuery) ; 



catch (SQLException se) 
{ 

log.errorC'Error in validating user."); 
1 og . errort "SQL statement = " + sQuery); 
se.printStackTrace( ) ; 

Modul eExcepti on me = new ModuleExcepti on( "error .db.sql ") ; 
throw me; 



finally 
( 

. finally code omitted 

) 

return user; 



Action mapping configuration 

Configuring the struts confi g file for the Logi nActi on is straightforward. 
You have to make sure to turn on validation by setting the validation 
attribute to true. 

You can take three possible directions from Logi nActi on: 

I If authorization fails, return to the h ome . j s p page. 

I If authorization succeeds, go to the m u s i c 1 i s t . d o action. 

If the user asks to join MusicCollection.com, go to the j o i n . j s p page. 
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Here is the action mapping for Logi nActi on: 




path=" /home" 

type="dummi es. struts. music. Logi nActi on" 
name=" 1 ogi nForm" 



scope=" request" 

i nput = " /home . jsp" 

val idate="true"> 
<forward name="f ai 1 ure" path=" /home . j sp" /> 
<forward name="success" path=" /musi cl i st . do" /> 
<forward name="join" path=" / j oi n . jsp" /> 
</acti on> 



Continued User Authentication 

Once the user has been authenticated, the application must continue to 
check the user's authorization for each protected page requested. As it turns 
out, every page except the Home and Join pages are protected. 

To accomplish this, we use our example of how to write a custom Request 
Processor found in Chapter 12, "Customizing the RequestProcessor Class." 
You can use the processPreprocess method in that example as a place to 
start. As a reminder, the processPreprocess method is called for each 
request that comes through the Struts controller. If the request is not for the 
Home or J o i n pages, then you need to verify that the user has been previously 
authenticated by looking forallserDTO object in the session. If the U s e r DTO 
object is not there, the user has not yet been authenticated and you need to 
redirect the request to the Home page so the user can log on. 

Listing 14-3 shows the processPreprocess method. 

Listing 14-3 processPreprocess Method of Custom RequestProcessor 

protected boolean processPreprocess(HttpServletRequest request, 

HttpServletResponse response) 

( 

boolean conti nueProcessi ng = true; 

// Test if the request is a login request 

try 

( 

HttpSession session = null; 
// make sure session has not timed out 
i f ( request . i sRequestedSessi on Id Val id() ) 
session = request. getSessiont ) ; 

else 

response. send Redi rect( "home. jsp? i n val id=yes" ) ; 



(continued) 
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// get the current request path 
String path = processPathtrequest, response); 



// if user is not trying to logon or join, make sure user has been authenticated 
if ((! path . equal s( (Stri ng) "/home"))&&( !path.equals((String) "/join"))) 
{ 

// get the user bean 

UserDTO user = (UserDTO) sessi on.getAttri bute( "user" ) ; 

// insure user has logged on 
if (user == null)// else make them logon first 
( 

try 
( 

response. send Red i rect( "home . jsp?i nval id=yes" ) ; 

) 

catcht Excepti on ioe) 
( 

log.errorC'problem redirecting in processPreprocess - " + 
i oe.getMessage( ) ) ; 

) 

conti nueProcessi ng = false; 



catch(Exception ioe) 
( 

log.errorC'problem processing path 
conti nueProcessi ng = false; 



" + i oe.getMessaget ) ) ; 



return continueProcessing; 



Struts is to be notified about the CustomRequestProcessor by adding it to 
the struts confi g file, as follows: 

<!-- =================== Controller Definition ============================= --> 

<control 1 er process or CI ass="dummi es . struts .musi c. CustomRequestProcessor" /> 



Creating a User Account 

In order to use the services of MusicCollection.com a prospective user must 
create an account. The Join page contains a form that the user fills out to 
create the account. 
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• Home page, a prospective user can create an account by clicking the 
on and going to the Join page. The Join page provides a form for the 
prospective user to enter the personal information necessary to create the 
account. The necessary fields are first name, last name, e-mail, and password. 
Since the password value is always hidden while typing, it is always a good 
practice to have the user enter the password twice to reduce the possibility of 
typing errors. Therefore, you can also include one additional password valida- 
tion field. 

After entering all the information, the user clicks on the Join button to submit 
the form. If the account is successfully created, the Welcome page is dis- 
played. If the user decides not to join, a Cancel button takes the user back to 
the Home page. See Figure 14-5. 



Figure 14-5: 

The Join 
page. 
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The Jain farm 

The Join page requires a dynamically generated ActionForm and is vali- 
dated using the Validator plug-in. Here you see the code segment that defines 

the Acti on Form in the struts -confi g file: 

<form-bean name=" joi nForm" 

type= "org. apache. struts. validator.DynaValidatorForm"> 
<f orm-property name="email" 

type=" Java . 1 ang . Stri ng" 
i n i t i a 1 = " " / > 
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<f orm-property name="password" 

type=" Java . 1 ang . Stri ng" 
i n i t i a 1 = " " / > 
rm-property name="password2" 

type=" Java . 1 ang . Stri ng" 
i n i t i a 1 = " " / > 
<f orm-property name="f name" 

type=" Java . 1 ang . Stri ng" 
i n i t i a 1 = " " / > 
<f orm-property name=" 1 name" 

type=" Java . 1 ang . Stri ng" 
i n i t i a 1 = " " / > 

</f orm-bean> 
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Join Validation 

Declarative validation is necessary for all the fields in the j o i n Fo rm. Each 
field is required and the ema i 1 field should look like an e-mail address. 
The content of the password field should be between 5 and 8 characters in 
length. Furthermore, the password2 field should match the contents of the 
password field to reduce the chances of a typographical error. 

We covered the creation of the necessary validators in the previous 
"LoginValidation" section except the requirement that password should 
match password2. With Struts 1.1, there is no out-of-the-box validator that 
provides this capability. (The val i dWhen validator will do what you need but 
will only be available in later versions of Struts.) So you have a choice of per- 
forming that validation within the Joi nActi on class or writing your own 
custom validator. While it is not too difficult to write a validator, we did not 
cover it when discussing the Validator plug-in in Chapter 9. Therefore, we 
have chosen to implement the password comparison test within the 
Joi nActi on code. 

In the val i dati on . xml file you need to specify the val i da tors for the 
j o i n Fo rm as follows: 

<form name=" joinForm"> 

<field property="f name" 

depends="required"> 
<argO key=" error .fname.required"/) 

</field> 

<field property=" 1 name" 

depends="required"> 
<argO key=" error .lname.required"/) 

</field> 

<field property="emai 1 " 

depends = " requi red , emai 1 "> 
<argO key="error .emai 1 .required"/) 
</field> 
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<f i eld property="password" 

depends="required,minlength' 
rgO key=" error . password. requi red' 
argl key=" $ { var :mi nl ength ) " name=' 
resource="fal se"/> 

<var> 

<var-name>minlength</var-name> 
<var-value>5</var-value> 

</var> 

</field> 



> 

/> 

mi nl ength" 



<f i eld property="password" 

depends="maxl ength") 
<argO key=" error .password. requi red "/> 
<argl key=" ${ var :maxl ength ) " name="maxl ength" 
resource="fal se"/> 

<var> 

<var-name>maxl ength</var-name> 
<var-value>8</var-value> 

</var> 
</field> 
</f orm> 



JoinAction 

The Joi nActi on is straight-forward, performing the following steps: 

1. Checks to see whether the user cancelled the action. If the user did 
request to cancel, return directly to the Home page. 

2 . Compares the password and password2 fields to make sure they match. 
If they do not, creates anActionError and returns it to the Join page. 

3. Creates a Joi nBean, passing the DataSource reference. 

4. Calls a method in Joi nBean, passing all user information, to create the 
user record in the database and return a populated UserDTO. The 

J o i n B e a n will create aUserDTO only after attempting to insert the 
user's information in the user table. The operation fails if there's an 
existing record with the same e-mail address. 

5. Puts the userDTO object into the session, logging the user onto 
MusicCollection.com. 

6. Forwards control to the Welcome page. 
Listing 14-4 shows the Joi nActi on execute method. 
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Blolean I 

3 BOQkS 



B|ol eau bCancel = 

(Bool ean) request . getAttr i bute( "org. apache. struts . act i on. CANCEL" ) ; 
'el != null) 
i f (bCancel . bool eanVal ue( ) ) 

return (mappi ng . fi ndForwardt "cancel ")) ; 
// compare password with password2 

if (( (St ring)((DynaValidatorForm)form).get("password2")).equals( (St ringH (DynaVal 
i da tor Form) form) . get ( "password" ) ) ) 

( 

// create a new JoinBean passing the datasource 

JoinBean jb = new JoinBean(getDataSource(request, "musi ccol 1 ecti on" ) ) ; 
// create an account for the user 

UserDTO user = jb.createUser((String)((DynaValidatorForm)form).get("fname"), 
(Stri ng) ( (DynaVal i da tor Form) form) .get( "1 name" ) , 
(Stri ng) ( (DynaVal i da tor Form) form) . get ( "emai 1 " ) , 
(Stri ng) ( (DynaVal idator Form) form) . get ( "password" ) ) ; 

if (user != nul 1 ) 
( 

// save UserDTO in session 

request .get Ses si on ( ) . setAttri bute( "user" , user ) ; 

return (mappi ng . fi ndForwardt "success" )) ; 

) 

else// could not add the use. Must be because already exists. 
( 

// create ActionError and save in the request 

ActionErrors errors = new ActionErrors( ) ; 

ActionError error = new Acti onError( "error .joi n . exi sts" ) ; 

errors . add ( "join" .error) ; 

saveErrors(request, errors); 

return (mappi ng.fi ndForward( "fai 1 ure" )) ; 



else// passwords did not match 
( 

// create ActionError and save in the request 
ActionErrors errors = new ActionErrors( ) ; 

ResourceBundl e bundle = ResourceBundle.getBundleC'ApplicationResources" 
ActionError error = new Acti onError( "error .joi n.passmi smatch" , 

bundle.getString("join.password2"), 
bundl e . get Stri ng( "join . password" ) ) ; 

errors. add ( "password2" .error) ; 

saveErrors(request, errors); 

return (mappi ng.fi ndForwardt "fai 1 ure" )) ; 



JoinBean 

The JoinBean gives the JoinAction the means to create a new user account 
by taking user information from the j o i n Fo rm and inserting a new row in the 
users table. The table has a unique index on the emai 1 column, thereby 
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throwing an error if an attempt is made to insert a new row with an emai 1 
value already in the table. The J oi nBea n tests for that possibility and returns 
ue for the UserDTO if the error occurs. If the insertion of the new 
iccessful, then a fully populated UserDTO is returned. If any other 
error occurs, the method throws a Modul eExcepti on. 



Listing 14-5 shows the createllser method of the J oi nBean. 



Listing 14-5 createllser Method of JoinBean 

public UserDTO createUser(String fname, String lname, String email, String 
password) throws ModuleException 

( 

UserDTO user = null; 
Connecti on con = null; 
Statement stmt = null; 
Resul tSet rs = null; 
String sQuery = " " ; 
try 
( 

con = dataSource.getConnection( ) ; 
stmt = con.createStatement( ) ; 
sQuery = "INSERT INTO Users (fname, lname, email .password, 

lastlogin.numlogins.created)"; 
sQuery += " values("' + fname + + lname + "' , "' + email + + 

password ; 
sQuery += " ' ,now( ) , 1 ,now( ) ) " ; 
int result = stmt.executeUpdate(sQuery) ; 

i f ( resul t == 1)11 insertion went ok, retrieve record to get id 
( 

sQuery = "SELECT * FROM Users " + "WHERE email = "' + email + ; 

sQuery += "AND password = "' + password + ; 

rs = stmt.executeQuery(sQuery) ; 

if (rs.nextO) 

( 

// Create new user transfer object 

user = new UserDTO( ) ; 

user . setFi rstName( rs .getStri ng( "fname" )) ; 

user . set Last Name ( rs . getStri ng( "1 name" ) ) ; 

user.setld(rs.getlnt("id")); 

user . set Emai 1 ( rs . getStri ng( "emai 1 " ) ) ; 

1 



catch (SQLException se) 
{ 

i f (se.getLocal i zedMessaget ) . i ndexOf ( "Dupl i cate" ) == -1) 
( 

log.errorC'Error in creating user."); 
1 og . errort "SQL statement = " + sQuery); 
se.printStackTrace( ) ; 



(continued) 
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ModuleException me = new Modul eExcepti on( "error .db.sql ") ; 
throw me; 



finally 



finally code omitted 



return user; 



Configuring the action mapping 
for Join Action 

When a user tries to join, three possibilities can occur. As a result, there are 
three possible directions to take from the Joi nActi on. 

I*** If a user account gets created, go to the wel come . j sp page. 
If a user account fails to be created, return to the j o i n . j s p page. 
*** If the user cancels the registration process, go back to the home . j sp page. 

Make sure to turn on validation by setting the validation attribute to t r u e . 
Here is the action mapping for Joi nActi on: 

<action path="/join" 

ty pe = " dumm i es. struts. music. Joi nActi on" 

name = " joi nForm" 

scope=" request" 

input="/join . jsp" 

val i date = "true"> 
<forward name="cancel " path = " /home . jsp"/> 
<forward name="f ai 1 ure" path=" / joi n . j sp" /> 
<forward name="success" path = " /wel come . jsp" /> 
</acti on> 



The Welcome page 

The Welcome page is displayed after the user successfully creates an 
account. This page presents a personalized welcome message along with a 
link to take the user to the main music display page. Figure 14-6 shows the 
Welcome page. 
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Figure 14-6: 

The 
Welcome 
page. 



File Edit View Favorites Tools Help BtSend jf 
»* • Si 9 B 6 ^Fevomes ^jfhMa ^) ^ Q lJ © 

^jocalhoit;MusicCoiection/|oin.do |,v] CI So Urte *' Norton Antivirus * 



CM-tisicCoCCection. com 



Welcome, Tom to MusicCollection.com 
Your user account has been created successfully and you have been logged on. 
Continue on to begin entering your music collection. 

continue 



Comments or Questions? Email Customer Support 

©2003 Mus.cCollertion.eom 



*J Local intranet 



Displaying the User's Albums 

When a user has logged on, the application retrieves the user's album infor- 
mation from the database and displays it in a list. From this page, the user 
can create, edit, or delete an album. There is also a Logoff button for the user 
to invalidate the user's session. 



The MusicList paqe 

On the MusicList page, we'll be displaying a collection of items, namely 
albums. This means we need to dig a little deeper into the JSTL tag library to 
discover some of the iterative tags. 

For each album displayed, we will show the following information: 

A number representing the row number of the album in the current list 

V The album name, which is also a link to the entire album record for edit- 
ing and viewing 

The individual or group who recorded the album 
j*" The year the album was released 

V A delete link that enables the user to delete the album from the collection 

In addition, the page has two buttons, as shown in Figure 14-7. The first 
is used to add a new album to the list, and the second is used to log off 
MusicCollection.com. Clicking the Add an Al bum button results in 
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Musi cLi stActi on forwarding the request to Al bumActi on. For the Logoff 
button, the Musi c Li stActi on redirects the request to Logoff Acti on. 



Figure 14-7: 

The 
MusicList 
page. 
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Tom's Album List 

| Add an Album | | Logoff | 





Album 


Artist 


Year 


Delete 


i 


Abbv Road 


The Beatles 


1969 


Delete 


2 


Girl Blue 


Stevie Wonder 


2003 


Delete 


3 


JaiUttal 


Shiva Station 


1997 


Delete 


4 


Magic ,J Mvric-ty T -w: 


The Beatles 


1968 


Delete 


5 


MiiTorbal] 


Sarah McLachlan 


1999 


Delete 


6 


Roots in the Sky 


Oregon 


1979 


Delete 


7 


Tree of Life 


Nancy Rumbel 


1995 


Delete 



Comments or Questions? Email Custom:-!- Support 

©2003 MuilcCollactlon.com 
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The MusicList form 

Because the MusicList page has no input fields, you might conclude that no 
form is necessary. However, several functions can be used from the page, 
namely creating a new album and logging off. (You can also edit and delete 
an album, but these actions are handled directly by Al bumActi on, not 
Musi cLi stActi on). Therefore, you need to have a way of specifying the par- 
ticular action to Musi c Li stActi on. 

To do so, you can create a hidden field named acti on that specifies the 
requested action. When the page is submitted, the value in the action field 
determines what function needs to be performed. 



The two actions are new , to create a new album, and logoff, to invalidate 
the user's session. Here is the form definition in the s t r u t s - c o n f i g file: 



<form-bean name="musi cl i stForm" 




type="org .apache. struts 


action.DynaActionForm") 


<form-property name="acti on" 




type=" Java . 1 ang 


Stri ng" 


initial-""/) 




</form-bean> 
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StActi on needs to handle three situations that can arise from a user's 
e first is displaying the user's list of albums. When Musi cLi stActi on 
is called, the acti on form variable determines what action should be per- 
formed. If acti on is null or empty, the request displays all the user's albums. 
MusicListBean does all the work to retrieve the album list. Musi cListAct ion 
just needs to instantiate the bean and pass it the user object. The bean returns 
the list of albums in a Collection, which Musi cLi stActi on puts into the ses- 
sion for use by the M u s i c L i s t page for display. 

If the action form variable's value is add, the user is requesting to create an 
album. Al bumActi on handles the creation of the new album. Therefore, con- 
trol is forwarded to newal bum Acti onForwa rd. 

The third possibility is when the action form variable equals 1 ogof f , which 
indicates that the user wants to log off the MusicCollection.com Web site. 
Control is forwarded to 1 ogof f Acti onForward, which is the Logof f Acti on 
class. 

Listing 14-6 lists the code for Musi cLi stActi on. 



Listing 14-6 MusicListAction Code 

public Acti onForward execute( Acti onMappi ng mapping, 
ActionForm form, 
HttpServletRequest request, 
HttpServl etResponse response) 
throws Exception 

( 

// determine the action, choices should be null, add, logoff 
String action = (Stri ng) ( (DynaActi onForm)form) . get ( "acti on" ) ; 
if ((action == null ) | (action. equalsC'"))) 
( 

// get the session object 

HttpSession session = request . getSessi on( ) ; 

// get the user object 

UserDfO user = (UserDTO)sessi on.getAttri bute( "user" ) ; 
// create a new LoginBean passing the datasource 
MusicListBean mlb = new MusicListBean(getDataSource(request, 

"musi ccol 1 ecti on" ) ) ; 
// get the music records for the user 
Collection ml = mlb.getMusic(user) ; 
// save MusicDTO collection in session 
sessi on.setAttri bute( "musi cl i st" ,ml ) ; 

1 

else if (action. equalsIgnoreCaseC'add")) // add a new album 
( 



(continued) 
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Listing 14-6 (continued) 

return ( ma ppi ng.fi nd Forward ( "newal bum" ) ) ; 
if (action. equalsIgnoreCaseC'logoff")) // logoff 
return ( ma ppi ng . fi nd Forward ( "1 ogoff " ) ) ; 

) 

return (ma ppi ng.fi ndForward( "success" ) ) ; 

1 



MusicListBean 

MusicListBean retrieves the albums that belong to a user and bundles them 
into a Col 1 ecti on. To do so, a DTO class, Al bumDTO, is created to hold the 
album information. However, because the Musi cLi st page displays only the 
al bum, arti st, and year fields, only those fields load into the Al bumDTO. 
The album i d doesn't display but is needed when a user requests to edit, 
view, or delete an album. 

Should anSQLException occur during processing, MusicListBean logs the 
offending error and throws a new ModuleException. Listing 1 4-7 shows the 
getMusi c method of Musi cLi stBean. 

Listing 14-7 MusicListBean getMusic Method 

public Collection getMusi c(UserDT0 user) throws ModuleException 
( 

Collection albums = new ArrayListO; 

Connecti on con = null; 

Statement stmt = null; 

Resul tSet rs = null; 

String sQuery = ""; 

try 

( 

con = dataSource.getConnection( ) ; 
stmt = con.createStatementt ) ; 

sQuery = "SELECT * FROM albums WHERE useri d=" + user . get Id ( ) ; 

sQuery += " ORDER BY album"; 

rs = stmt.executeQuery(sQuery) ; 

while (rs.nextO) 

( 

// Create new user transfer object 

AlbumDTO album = new AlbumDTOO; 

al bum.setAl bum( rs . getStri ng( "al bum" ) ) ; 

al bum. setArti st( rs . getStri ng( "arti st" ) ) ; 

al bum. set Id ( rs . get I nt ( "id" ) ) ; 

al bum.setYear( rs .getStri ng( "year" )) ; 



DropBooks 
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// save the album in the collection 
albums. add(album) ; 



catch (SQLException se) 

log.errorC'Error in retrieving albums."); 
log.errorC'SQL statement = " + sQuery); 
se.printStackTrace( ) ; 

ModuleException me = new ModuleExcepti on( "error .db.sql ") ; 
throw me; 



finally 

fina 1 ly code omitted 
return albums; 



Configuring action mapping 
for MusicListAction 

You don't need to perform validation on Musi cLi stForm, so you should turn 
it off in the action mapping by setting the v a 1 i d a t i o n attribute to false. 
Three possible directions can be taken from Musi c Li st Act i on, so three for- 
wards need to be defined in the action mapping: 

V If the user requests to log off, go to the 1 ogof f . do action. 
If the user requests a new album, go to the a 1 bum . do action. 
To display the list of albums, go to the musi cl i st . jsp. 



Here is the action mapping for Musi c Li st Act i on: 

<action path=" /musi cl ist" 

type = "dummi es . struts . musi c . Musi cLi stActi on" 

name = "musi cl i stForm" 

scope=" request" 

i nput=" /musi cl i st . jsp" 

val i date = "f a 1 se" > 
<forward name=" 1 ogof f " path = " /l ogof f . do" /> 
<forward name="newal bum" path = " /al bum . do" /> 
<forward name="success" path = " /musi cl ist. jsp"/> 
</acti on> 
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Creating, Editing, or Deleting an Album 

DropBooks 

delete an 



lib um page, users can view the details of any album, add an album, or 
delete an album that they no longer want on their list. Therefore, you need a 
section of the application to handle the following: 

W Displaying the details of an album 
u* Ensuring that the data is acceptable 
v 0 Creating album database records 
v 0 Deleting album database records 



The Album paqe 

The Al bum page contains the complete set of information about the album. In 
addition to the album name, artist, and year of release (displayed as a Sel ect 
list), the Al bum page also contains information not normally displayed in the 
Musi cLi st page, as follows: 

\S type: The album can be recorded on vinyl, tape, CD, or MP3. The type is 
displayed as an HTML Sel ect list. 

category: The category describes the genre or category of music that 
the album belongs to. Choices are Classical, Country, Easy Listening, 
Heavy Metal, Jazz, New Age, Pop/Rock, R & B, and World. The category 
is displayed as an HTML Sel ect list. 

descri pti on: This is a free-form comment field that enables the user 
to add a comment about the album. The description is displayed as 

TextArea. 

The user can accept changes made to the page (Save button) or discard 
changes (Cancel button) by clicking the appropriate button. Figure 14-8 
shows the Al bum page. 



AtbumForm 

The Al bumForm form has the normal assortment of properties — one for each 
field displayed on the Al bum page. Because we also have three Sel ect lists 
for years, types, and categories, we need additional properties to contain the 
arrays that populate the Sel ect tags. 

To create these three arrays, you can use a custom plug-in designed to initialize 
various application parameters at startup with the StartupManager plug-in. 
(See the next section for details.) 
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Figure 14-8: 

The Album 
page. 
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Editing an Album 



Album Title Abby Road 



Artist The Beatles 
Year Recorded 19E9|vj 
Media L P [v] 
Category Pop/Rock vl 



Original album, unopened. 



Updale Cancel 



Comments or Question: £1:1^ 'J.mi-. ;r.cr Support 

©2003 MusicCollettion.com 



Furthermore, you need to keep track of the i d (album), useri d, and what- 
ever acti on needs to be performed. Therefore, these fields are also present 
in the al bumForm, as shown here: 

<form-bean name="al bumForm" 

type=" org. apache . struts . val i da tor . DynaVal i da tor Form") 
<form-property name="album" 

type=" Java . 1 ang . String" 

i n i t i a 1 = " " / > 
<form-property name="arti st" 

type=" java . 1 ang . String" 

i n i t i a 1 = " "/ > 
<form-property name="year" 

ty pe=" j a va . 1 ang . String" 

i n i t i a 1 = " " / > 
<form-property name="type" 

type="java.lang. String" 

i n i t i a 1 = " "/ > 
<form-property name="category" 

type=" j ava . 1 ang . String" 

initial-""/) 
<form- property name="descri pti on" 

ty pe=" j ava . 1 ang . String" 

initial-""/) 
<form-property name="userid" 

type=" j ava . 1 ang . String" 

initial-""/) 
<form-property name="id" 

type=" j ava . 1 ang . String" 

initial-""/) 
<form-property name="actionl" 

ty pe=" j a va . 1 ang . String" 

initial=""/> 
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<form-property name="years" 

type=" Java . uti 1 . Array List"/) 
m-property name="medias" 

type=" j a va . uti 1 .Array Li st"/> 
<form- property name="categori es" 

type=" java . uti 1 . Array List"/) 

</form-bean> 



StartupManager 

In Chapter 9 we provide an example of a custom plug-in called StartupManager 
that initializes various application resources at startup and releases resources 
in an orderly way at shutdown. You can use StartupManager in this applica- 
tion to initialize the arrays needed by the Al bum page and to release the 
DataSource resources when the application shuts down. 

Be sure to add the plug-in to the struts confi g file like this: 

<pl ug-i n cl assName="dummi es. struts. mu sic. StartupManager" /> 



AlbumValidation 

Many of the fields do not need validation because they are HTML Select lists 
that are guaranteed to have a valid value. Furthermore, the Description 
field is optional and may contain anything. That leaves just the a 1 bum and 
artist fields that should be filled in before the page is accepted. Here is 

va 1 i dati on . xml for al bumForm: 

<form name="al bumForm"> 

<f i eld property="al bum" 

depends=" requi red"> 
<argO key="error .album. requi red "/> 

</field> 

<f i eld property="arti st" 

depends=" requi red" > 
<argO key=" error . art ist. requi red "/> 

</field> 
</f orm> 



AtbwmActhn 

To allow users to manage their album list, Al bumActi on has to be able to 
handle six actions: 
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Creating an album 
Editing an album 



ting an album 
Saving a new album 
*** Updating an album 

Canceling the editing or creation of an album 

Because of the various tasks involved, Al bumActi on is the most complex 
class in the application. Consequently, we examine this class in sections. 

determining the requested action 

The first thing to consider is how the execute method determines what action 
needs to be performed. Requests can come from two sources — directly or 
indirectly from the Mus i c Li st page (create, edit, and delete actions) and from 
the Al bum page itself (save, update, or cancel). To handle these various sources, 
Al bumActi on needs to look at two action properties. One property comes as 
a form property from the Album page. The other comes as a request parame- 
ter when the Al bumActi on is being called from the Musi cLi st page directly: 

// determine the action, values can be null, 'save', 'update', or 'cancel' 
String action = (String) ( (DynaVal idatorForm)form) . get ( "acti onl" ) ; 
// acti on2 can be either null, empty or contain 'view' or 'delete' 
// comes directly from musiclist 

String acti on2 = (String) request .getParametert "acti on2" ) ; 
i f ( acti on2 ! =nul 1 ) 

i f ( ! acti on2. equal s( " " ) ) 

action = acti on2 ; // replace action with acti on2 if action? is not empty 

The preceding code segment, at the beginning of Al bumActi on, determines 
which action to take. Notice that acti on2 comes from the request parame- 
ter. If acti on 2 is not empty, you can assume that the request came directly 
from the Musi c Li st page and is either 'view' or ' del ete '. You replace the 
current value ofactionwiththe value inaction2.Ifaction2is empty, you 
keep the value of the acti onl parameter that was put in the acti on variable. 

Creating an album 

If acti on is null or empty, the request is to create an album. The following 
code segment shows how this is accomplished: 

i f ( ( acti on == null ) | (action. equalsC'"))) // request came from musiclist to 
create an Album 



Servl etContext sc = thi s .getServl et( ) .getServletContextt ) ; 

( (DynaVal idator Form) form) . set( "years ".(Array Li st)sc. getAttri bute( "years" )) ; 
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( (DynaVal idatorForm) form) .set ( "types" , ( Array Li st)sc.getAttri bute( "types" ) ) ; 
( (DynaVal i da tor Form) form) . set ( "categori es" , 

(Array Li st )sc. getAttri bute( "categories" )) ; 
rn (mappi ng . fi ndForwardt "new" )) ; 



This code populates the yea rs, types, and categori es arrays of al bumForm 
from the application scope, where the arrays were stored byStartupManager 
during the startup phase. Control then passes to the new Acti on Forward, 
which points to the al bum . j sp page. Notice the use of the Map key-value pair 
mechanism for getting and setting values in DynaVal idatorForm (likewise 
for DynaActi onForm). 

Editing or Viewing an existing album 

The next possibility that you need to check for is viewing an album. The fol- 
lowing code segment performs that task: 

else if(action.equalsIgnoreCase("view")) // request came from musiclist to edit 
an Album 

( 

// get the id of the album 

int id = convert I D( ( St r i ng ) request. getParameter( "id" )) ; 

If (id > 0) 

( 

// create a new AlbumBean passing the datasource 

AlbumBean ab = new AlbumBean(getDataSource(request, "musi ccol 1 ecti on" ) ) ; 
AlbumDTO album = ab.findAlbum(id) ; 

Servl etContext sc = thi s . getServl et( ) .getServl etContextt ) ; 
xferToForm( album, form, sc) ; 

) 

return (mapping.fi ndForwardt "new" ) ) ; 



If the request is to view an album, the first thing to do is to retrieve the request 
parameter id. The convertID method then converts it from a Stri ng to an 
int. Here is the convertID code: 



private int convertID(String id) throws ModuleException 
{ 

int idNum = 0; 

if(id != null)// id should contain the id of the album to delete 
i f( ! id. equal s( "") )// then user is request to delete an album 
( 

// convert the String id to int id 

try 

( 

idNum = Integer. parselnt(id) ; 

1 
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catch(NumberFormatException nfe) 
{ 

log.errorC'error in converting string to a number"); 
1 og. error (nfe. get Local i zedMessaget ) ) ; 

ModuleException me = new ModuleExcepti on( "error .nfe. message" ) ; 
throw me; 



return idNum; 

) 

After a valid ID is returned, Al bumBean is created. The f i ndAl bum method of 
Al bumBean is passed the album i d, returning the album in the form of a DTO 
named Al bumDTO. The Al bumDTO data is inserted in al bumForm through the 
use of the private xf erToForm method, as follows: 

private void xferToForm(Al bumDTO album, ActionForm form, Servl etContext sc) 
( 

( (DynaVal i da tor Form) form) .set( "al bum" , al bum.getAl bum( ) ) ; 

( (DynaVal i da tor Form) form) .set( "arti st" , al bum. getArti st( ) ) ; 

( (DynaVal i da tor Form) form) .set ( "descri pti on" , al bum.getDescri pti on( ) ) ; 

( (DynaVal idator Form) form) . sett "year" , al bum.getYear( ) ) ; 

( (DynaVal i da tor Form) form) . sett "category" , al bum. get Category ( ) ) ; 

( (DynaVal idator Form) form) . sett "type" , al bum.getType( ) ) ; 

( (DynaVal idator Form) form) .set( "id" , Stri ng. val ueOf (al bum. get Id ( ) ) ) ; 

( (DynaVal idator Form) form) . sett "userid" , Stri ng. val ueOf (al bum.getUseridt ) ) ) ; 

( (DynaVal idator Form) form) . sett "years" , ( Array Li st )sc.getAttri butet "years" )) ; 

( (DynaVal idator Form) form) . sett "types" , (Array Li st )sc . getAttri butet "types" ) ) ; 

(( Dy naVal i dator Form) form ).set(" categories", 

(ArrayList)sc. getAttri bute( "categories" ) ) ; 

1 

For the most part, this method just moves the properties from Al bumDTO into 
a 1 bumForm. However, to populate the three array properties used for the HTML 
Sel ect lists, you need to retrieve the arrays from the application scope. Hence 
you need to pass the Servl etContext reference to the method. 

Finally, the Al bumActi on code returns the newActionForward object, which 
passes control to the a 1 b u m . j s p page. 

Deleting an album 

The final action that can come from the Musi cLi st page is to delete an album. 
The code is a little simpler than editing an album because there is no need to 
transfer data to the form: 

else if(action.equalsIgnoreCase( "delete" ) )// request from musiclist to delete an 
Al bum 

( 

// get the id of the album 

int id = convert I D( ( St r i ng ) request. getParameter( "id" )) ; 
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if (id > 0) 
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// create a new AlbumBean passing the datasource 

lAlbumBean ab = new AlbumBean(getDataSource(request, "musi ccol 1 ecti on" )) ; 
ab.deleteAlbum(id) ; 



As with editing an album, you use a request parameter to pass the album i d 
data. If the i d is valid, a new Al bumBean is created and the del eteAl bum 
method is called with the album i d. Acti onForward used is the general 
success forward at the end of the execute method. 



Canceling the creation or editing of an album 

The next three requests are cancel, save, or update an album. These 
requests come from the Al bum page itself. Here is the code when a cancel 
action is detected: 

else if (acti on. equal sIgnoreCase( "cancel ") ) // abandon adding/modifying an album 
( 

return (mapping.findForward( "cancel ")) ; 

) 



The cancel forward returns control to the Musi c Li st page. 



Saving or updating an album 

The final two requests are handled in one section of code. The only difference 
is whether album data is inserted new into the database (saving) or an exist- 
ing record is updated. Here is the code: 

else if ((acti on. equalsIgnoreCaset" save")) | (acti on. equal slgnoreCaset" update"))) 
( 

ActionErrors errors = ((DynaValidatorForm)form).validate(mapping, request); 

i f (errors . i s Empty ( ) ) 

( 

// get the session object 

HttpSession session = request . getSessi on( ) ; 

// get the user object 

UserDTO user = (UserDTO)sessi on.getAttri bute( "user" ) ; 

// initialize a fresh AlbumDTO 

AlbumDTO album = new AlbumDTOO; 

// move form info to album 

xferToBean( form, album, act ion, user) ; 

// create a new AlbumBean passing the datasource 

AlbumBean ab = new AlbumBean(getDataSource(request, "musi ccol 1 ecti on" )) ; 
// if action == save, insert the new album 
if(action.equalsIgnoreCase("save")) 

ab.saveAlbum(album) ; 
else // must need to update existing album 

ab.updateAlbum(album) ; 
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else // there were validation errors 




saveErrorstrequest, errors); 
return (mappi ng . f i ndForwardt "fai 1 ure" ) ) ; 



The first thing you might notice is that the code performs validation manu- 
ally. We do this because we forward directly to a 1 bum . do in the Mus i c Li st 
page rather than forward to the a 1 bum . j sp page, thus avoiding having a JSP 
file show up in the URL. The downside is that you can't have the validator 
automatically perform validation because initially the form's properties are 
empty, an unacceptable state for the validation process. Therefore, we manu- 
ally call the validate method only when we know that the properties of the 
form are populated. 

You could eliminate this nonstandard mechanism by removing the <A HREF> 
tag and using JavaScript to process an oncl i ck condition. The JavaScript 
code could then perform a forward to the a 1 bum . j s p page without changing 
the current URL. (We didn't use this technique because it would have added 
more complexity than would have been suitable for this example application.) 

If validation errors are detected, the errors are saved in the request and con- 
trol returns to the Al bum page. 

If no validation errors are returned, you get the UserDTO object from the ses- 
sion to pass to the xferToBean method. You create an empty Al bumDTO 
object to hold the form properties and call the private xferToBean method 
to transfer all the form's properties to Al bumDTO. Listing 14-8 shows the 
xferToBean method. 



Listing 14-8 xferToBean Method 

private void xferToBean(Acti onForm form, Al bumDTO album, String action, UserDTO 
user) throws ModuleException 

( 

al bum.setAlbumt (String) ( (DynaVal i da tor Form) form) .get ( "al bum" ) ) ; 

al bum. setArti st( (St r i ng) ( (DynaVal idator Form) form) . get( "arti st" ) ) ; 

al bum. setDescri pti on( (Stri ng) ( (DynaVal idator Form) form) . get ( "descri pti on" ) ) ; 

album. setYear( (Stri ng) ( (DynaVal idator Form) form) . get ( "year" ) ) ; 

album.setType( (Stri ng) ( (DynaVal idator Form) form) . get ( "type" ) ) ; 

al bum. set Category ( (Stri ng) ( (DynaVal idator Form) form) . get( "category" ) ) ; 

if(acti on. equal slgnoreCaseC update")) 



al bum.setUseridt Integer . parselntt 

(StringM (DynaVal idator Form) form) . get ( "user id" ) ) ) ; 

(continued) 
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album, set I d( Integer.parselnt( (StringX (DynaVal i da tor Form) form) . 
getC'id"))); 



catch(NumberFormatException nfe) 
( 

log.errorC'error in converting string to a number"); 
1 og. error (nfe .get Local i zedMessage( ) ) ; 

ModuleException me = new ModuleExceptionC'error. nfe. message"); 
throw me; 

) 

1 

else// assume creating a new album, so no userlD or ID available in form 
{ 

al bum. setUserid( user .get Id ( ) ) ; 
album. setld(O) ; 



The xferToBean method simply transfers the form properties to the DTO. If 
the action is update, the useri d and album i d already exist in the form and 
can be transferred directly to the DTO. If the action is save, the useri d and 
album i d values will not exist in the form. Therefore, it is necessary to get 
the useri d from the User DTO and set the album i d to 0. 

When the Al bumDTO has been populated, an Al bumBean is created which, 
depending on the action, calls either the saveAl bum or updateAl bum method, 
passing the Al bumDTO object. 

The Act ion Forward used is the general success forward at the end of the 
execute method, which returns control to the Musi c Li st page. 



Al bumBean performs all the database interactions involving single albums. 
For this purpose, you can use four methods: 

f i ndAl bum 
V del eteAl bum 
updateAl bum 
saveAl bum 

These methods are discussed in the following sections. 
Finding an album 

The f i ndAl bum method receives an album i d and uses that i d to search for 
the album. The method is shown in Listing 14-9. 



AtbumBean 
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Statement stmt = null; 
Resul tSet rs = null; 
Stri ng sQuery = " " ; 
Al bumDTO al bum = null; 

try 

( 

con = dataSource.getConnection( ) ; 

stmt = con.createStatement( ) ; 

sQuery = "SELECT * FROM albums WHERE ld=" + id; 

rs = stmt.executeQuery(sQuery) ; 

if ( rs .next( ) ) 

( 

al bum = new Al bumDTCK ) ; 

al bum.setAl bum( rs.getStringt "al bum" ) ) ; 

al bum.setArti st( rs .get Stri ng( "artist")); 

al bum.setDescri pti on( rs .getStri ng( "descri pti on" ) ) ; 

al bum. set Id ( rs . get I nt ( "id" ) ) ; 

a 1 bum . setUser i d ( rs .getlntC'userid")); 

al bum. setYeart rs .getStringC'year")); 

al bum. setType( rs . getStri ng( "type" ) ) ; 

al bum.setCategory( rs .getStri ng( "category" )) ; 



catch (SQLException se) 
1 

log.errorC'Error in finding album."); 
log.errorC'SQL statement = " + sQuery); 
se.printStackTrace( ) ; 

Modul eExcepti on me = new ModuleExcepti on( "error .db.sql ") ; 
throw me; 



The query is for an album with the specified album id. If an album record is 
found, Al bumDTO is populated with the album data and returned. The code 
logs any SQLExcepti on and throws a Modul eExcepti on. 



Listing 14-9 findAlbum Method 




throws ModuleException 



final ly 



. fina I ly code omitted 



return album; 
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Deleting an album 

■— ^ Ar|album id is passed to the del eteAl bum method, just like in f i ndAl bum. 

1 1T\ f\ ^Tltrer^^in not returning a value, the only difference between del eteAl bum 

L-^ I V^LJU Vh6\l*lAlbumisinthetryblock: 

try 
( 

con = dataSource.getConnectiont ) ; 

stmt = con.createStatement( ) ; 

sQuery = "DELETE FROM albums WHERE id=" + id; 

int result = stmt.executeUpdate(sQuery) ; 

) 



The SQL statement requests deletions of an album with the same 


i d as the 


passed album i d. 




Saving an album 




The sa veAl bum method, like the del eteAl bum method, does not return a 


value. This method, however, receives an Al bumDTO instead of an 


album i d. 


The following try block sets it apart from the other methods of Al bumBean: 


try 

( 




con = dataSource.getConnectiont ) ; 




stmt = con.createStatement( ) ; 




sQuery = "INSERT INTO albums (album, artist, year, type, category,"; 




sQuery += "description, userid, created)" ; 




sQuery += " v a 1 u e s ( ' " + fi 1 ter ( a 1 bum. get Al burnt ) ) + "',"'; 




sQuery += f i 1 ter ( a 1 bum.getArti st( ) ) + "',"'; 




sQuery += album. getYear( ) + "',"'; 




sQuery += album. getType( ) + "',"'; 




sQuery += al bum.getCategory( ) + "',"'; 


sQuery += f i 1 ter ( a 1 bum.getDescri pti on( ) ) + "',"; 


sQuery += album. getUseridt ) +","; 


sQuery += "now( ) ) " ; 


int result = stmt.executeUpdate(sQuery) ; 

1 



The SQL INSERT statement is created with the values of the Al bumDTO prop- 
erties. For those String properties that a user may enter by hand, you use a 
quick filter to replace any single quotes with a pair of single quotes. You need 
the two single quotes to avoid causing errors in the SQL statement: 



private String filter(String value) 
{ 

return value. repl aceAl 1 ( , ); // replace 1 single quote with 1 single 

quotes 

1 
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Updating an album 

Finally, Jhe updateAl bum method also receives an Al bumDTO as a parameter 
ns nothing. Its try block looks like this: 



con = dataSource.getConnection( ) ; 
stmt = con.createStatement( ) ; 
sQuery = "UPDATE albums "; 

sQuery += "SET a 1 bum= ' " + Ti 1 ter(al bum.getAl bum( ) ) + 

sQuery += "artist="' + f i 1 ter(al bum.getArti st( ) ) + 

sQuery += "year="' + album. getYear( ) + 

sQuery += "type="' + album. getType( ) + 

sQuery += "category="' + album. getCategory( ) + 

sQuery += "description"'" + f i 1 ter(al bum.getDescri pti on( ) ) + 

sQuery += "userid=" + album. getUserid( ) ; 

sQuery += " WHERE id =" +album.getld( ) ; 

int result = stmt.executeUpdate(sQuery); 



The SQL statement updates an existing album record that has the album i d 
found in Al bumDTO. Again you can use the filter method on some properties 
to escape (render harmless) single quotes. 



Configuring action mapping (or AibumAction 

Al bumActi on performs validation manually for reasons explained in the 
"AibumAction" section earlier in this chapter. You turn automatic validation 
off by setting the validation attribute to f a 1 s e . 

There are four possible directions that Al bumActi on can take: 

If the user cancels the edit or creation of an album, go to the musi cl i st . 
do action. 

f" If the user updates the edit or saves the creation of an album, go to the 

musi cl i st . do action. 

If the user wants to create a new album, go to the a 1 b urn . j s p page. 

If validation errors are detected when the user submits the al bumForm, 
return to the a 1 bum . j s p page. 



Here is the action mapping for Al bumActi on: 



<action path="/al bum" 

type = "dummies. struts. music.Al bumActi on" 
name="al bumForm" 
scope=" request" 
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input="/al bum. jsp" 
val i date="f al se" > 
forward name="cancel " path = " /musi cl i st . do" /> 
riorward name="success" path = " /musi cl i st . do" /> 
<forward name="new" path="/al bum. jsp"/> 
<forward name="f ai 1 ure" path="/al bum. jsp"/> 
</acti on> 



Loqqinq Off 

Logging the user off the Web site is important for both security and resource 
reasons. The Musi cLi st page has a Logoff button that forwards control to 
the execute method in Logoff Acti on. 



LoqoffAction 

Logoff Acti on is primarily responsible for invalidating the user's session, 
but it also provides some useful information for the application log file. Here 
is the body of the execute method for Logoff Acti on: 

// retrieve the user object 

HttpSession session = request. getSession( ) ; 

UserDTO user = (UserDTO) session. getAttri bute( "user" ) ; 

// write logoff info to application log 

if (user != null ) 

( 

log. info ("Logoff Acti on: User "' + user .getFi rstName( ) + "' logged off in 
session " + session. getld ( )) ; 

1 

el se 

( 

log. info ("Logoff Acton: User logged off in session " + sessi on . get Id ( ) ) ; 

1 

// make the session invalid 
sessi on . i nval i date ( ) ; 

// Forward control to the specified success URI 
return (mappi ng . fi ndForward( "success" )) ; 

When the UserDTO object is retrieved from the session, you can log a mes- 
sage about the user. Invalidating the user's session really performs the act of 
logging the user off. Control then passes to the Home page. 
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Configuring action mapping 

D ro p Bo<jk& a (f Act ' an 

The standard procedure after logging off is to return to the Home page. Here is 
the action mapping for Logoff Acti on: 



<action path=" /l ogof f " 




type="dummies. struts. music 


. Logoff Acti on" 


scope=" request" 




val i date = "f al se" > 




<forward name="success" path=" 


/home. jsp"/> 


</acti on> 





Handling Exceptions 

This application makes use of many of the error-handling features discussed 
in Chapter 8. The exception choices require very little in the way of imple- 
mentation because CustomExcepti onHandl er is written in Chapter 8. 



Our ortn exception 

We use Modul eExcepti on for the application exceptions, as we do in Chapter 
8. Modul eExcepti on allows you to pass a resource key that will create an 
Acti onError object stored in Modul eExcepti on. In this way, you can pro- 
vide I18N support in your exception error messages. 



The custom Exception Handler 

To provide more data on exceptions, the application uses CustomExcepti on 
Handler, which is developed in Chapter 8. (To check it out, see the "Exception 
Information" section in Chapter 8.) CustomExcepti onHandl er provides com- 
plete logging of the exception stack trace, including chained exceptions. Struts 
is notified of its existence by adding one or more exception tag definitions that 
reference it (as detailed next). 
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e two exceptions to be global: Modul eExcepti on and Runtime 
n.ModuleExceptionisan application-thrown exception used for 
errors that we detect during execution. The infamous Runti meExcepti on is a 
nonrecoverable error thrown by the runtime system. Rather than showing a 
stack trace to the user, you can catch the error and display your own, more 
friendly error page. Here's the code: 

< ! --==========G1 obal Excepti onDef i ni ti ons==========================--> 

<!---key value will be taken from the ModuleException instance-- --> 

<gl obal -excepti ons> 

<excepti on bundl e = " A p p 1 i cat i on Resources" 
key=" " 

path="/error. jsp" 

handl er="dummi es .struts .musi c.CustomExceptionHandl er" 
type=" org. apache. st ruts. uti 1 .ModuleException"/) 
<excepti on bundl e=" Appl i cat i on Resources" 
key=" error . Run time Excepti on" 
path="/baderror. jsp" 

handl er="dummi es .struts .musi c.CustomExceptionHandl er" 
type=" Java . 1 ang. Runti meExcepti on"/> 
</gl obal -excepti ons> 



Both exceptions use CustomExcepti onHandl er, which we created for better 
error logging. Modul eExcepti on uses the error . jsp page to display its 
error messages; Runti meExcepti on uses the baderror . jsp page. 

Error pages 

Because you are handling two types of exceptions (Modul eExcepti on and 
RuntimeExcepti on), you need to display two error pages. 

For Modul eExcepti on, the error . jsp page contains the error message that 
the application stores in Modul eExcepti on. This message should be as clear 
and nontechnical as possible, because it needs to tell the user what hap- 
pened and how to proceed. A link on the page enables the user to return to 
the page containing the list of albums, which is not too helpful if this is the 
page causing the exception. A second link allows the user to log off the 
MusicCollection.com Web site if the first link causes another exception. 
Figure 14-9 show how the page looks. 

If a more serious error occurs (that is, RuntimeExcepti on), the user should 
just log off immediately. A standard error message appears, indicating the 
seriousness of the situation. Figure 14-10 shows the baderror . jsp page. 
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Running the Application 

At the Web site for this book (www .dummies, com/go/ Jakarta), you can 
download this application as a compressed or uncompressed archive. The 
archive includes all files necessary to run the application, including all the 
library files. It also contains the SQL script for creating the database and 
tables in a MySQL database. 
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up your database schema as described in the beginning of this 
ter. 



2. Modify DataSource in the struts confi g file to accommodate the 
particulars of your database connection. 

3. If you use a different database driver than the one we provide, 
replace our driver with yours in the WEB INF/lib folder. 

You will also need to modify the DataSource definition in the struts - 
conf i g . xml file to specify your database driver. 

The intention of the MusicCollection.com application is to give you exposure 
to the various features and extensibility of the Struts framework. By working 
through the example, you should gain familiarity with the power and flexibil- 
ity Struts can offer you. To see a running version of the MusicCollection.com 
application, go to 

www .othenos.com/musiccollect ion/ 
Be sure to include the last slash. Good luck! 
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In this part . . . 

MJart V is the famous Part of Tens contained in every 
V For Dummies book. In Chapter 15 we offer ten helpful 
extensions to Struts to make your programming go more 
smoothly. In Chapter 16 we list ten ways to find more 
information on Struts, including the Struts Web site, dis- 
cussion groups, articles, resource Web sites, and sample 
applications. You'll find lots of helpful material here. 
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In This Chapter 

ImageButtonBeanManager 

Struts Spring plug-in 

Hibernate 

Expresso 

SSLExt 

Struts Action Scripting 
StrutsDoc 

StrutsTestCase for JUnit 
Struts workflow extension 
Easy Struts plug-in 



• •••••• 



I\ fter a product gains a following, improvements and additions are sure 
¥ \ to follow. Struts has been downloaded hundreds of thousands of times 
over the past several years, so that qualifies as popular! As developers create 
diverse applications with Struts, they also develop solutions to common (and 
not so common) problems. Sometimes these solutions are general enough to 
be of use to other people. And sometimes the developers see fit to generously 
make these solutions available to others through the open-source process. 

In this chapter, we describe a sampling of these open-source solutions that 
you can use. Not all of these packages were developed specifically for Struts, 
but they're all useful nevertheless. 



ImageButtonBeanManager 

ImageButtonBeanManager is a niche package, but if you have the need, it fills 
the bill quite nicely. ImageButtonBeanManager is a Struts extension that sup- 
ports the Image tag in the Struts HTML tag library and the org. apache, 
struts . uti 1 . ImageButtonBean class. This support is like the support pro- 
vided by the LookupDispatchAction class for multiple Submit buttons (as 
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discussed in Chapter 4). With this extension, the LookupDispatchAction 
class can recognize when the user has selected one of many images and pass 
p the appropriate handler method. 



The documentation for this package is complete and useful. To download 
ImageButtonBeanManager, visit 

sourceforge. net/pro jects/imagebuttonbean 



Stmts Spring PluqAn 



Computer scientists are always trying to find ways to reduce dependencies 
in code. In other words, they attempt to have the loosest coupling possible. 
Loose coupling creates code that exhibits a high degree of flexibility and is 
resilient to changes elsewhere in the application. The Struts Spring plug-in 
allows developers to take greater advantage of this principle by integrating 
the Inversion of Control (I°Q mechanism from Spring's J2EE framework into 
Struts. IoC is also known as The Hollywood Principle — don't call us, we'll 
call you — and effectively reduces dependencies in classes. With this plug- 
in, a Struts application can take advantage of IoC with little or no references 
to Spring. 

Documentation for Spring's J2EE framework is extensive. You can read more 
about Spring's J2EE framework at their Web site at 

www . spri ngf ramework . org 
To download the Struts Spring plug-in, go to 

struts. sourceforge. net/struts - spring 

The plug-in documentation is sparse, but the downloaded package includes 
an example application using the plug-in. 



Hibernate 

Hibernate is an open-source project designed to take the work out of getting 
Java objects to and from a relational database. Hibernate provides a transpar- 
ent persistence mechanism for Java objects as well as a flexible ORM (Object 
Relational Mapping) tool for use with a large selection of open-source and com- 
mercial databases. In addition, Hibernate implements it own Hibernate Query 
Language as an object-orientated extension to Standard Query Language (SQL). 
Hibernate developers claim that the Hibernate plug-in is the most widely-used 
ORM tool in the Java marketplace. 
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Because Hibernate concerns only the persistence of Java objects, it integrates 
easily with Struts. To see some examples of Struts applications that use 
,e, look at the hibernate link at 



forge. net/projects/struts 
To read more about Hibernate or to download the code, visit 

www . hi bernate.org 



Expresso 

Expresso, like Struts, is a large, open-source, Java-based application frame- 
work. In fact, Expresso contains Struts. 

Expresso focuses on providing an implementation of the Model layer of the 
MVC pattern. This plug-in comes already integrated with Struts and adds 
many new capabilities to the Struts framework. The Expresso framework 
includes 16 separate but integrated components. You may choose to use one 
or all of them, as you see fit. Expresso adds to or supplements Struts capabili- 
ties in the following areas: 

f Security 

V Robust object-relational mapping 

V Background job handling and scheduling 
Self-tests 

«" Logging integration 

Automated table manipulation 
W Database connection pooling 

V E-mail connectivity 
Event notification 

i>* Error handling 
Caching 

Internationalization 
v* XML automation 
u* Testing 



u* Registration objects 
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I Configuration management 
Workflow 



matic database maintenance 
For further information on Expresso, visit 

www . j corporate. com/index. html 



SSLExt 



If you'd like to use the https protocol (http protocol with the Secure Socket 
Layer protocol underneath) to secure some but not all pages in your Struts 
application, consider using the SSLExt plug-in. SSLExt allows developers to 
configure Struts applications to automatically switch between the http and 
https protocols. You define this configuration in the strutsconfig.xml file. 

You can find succinct documentation at ssl ext . sourcef orge . net. To 
download the plug-in, go to 

sourceforge. net/pro jects/ssl ext 



Stmts Action Scripting 

If you're proficient in any of the myriad of scripting languages, you may be 
wishing you could use that skill for writing Struts Acti on classes. Wish no 
longer — IBM's Alphaworks provides a solution that they call Struts Action 
Scripting. 

Struts Action Scripting is a Struts plug-in that allows you to develop Struts 
actions with almost any scripting language. The plug-in provides a Struts 
Acti on class called Scri ptedActi on. The Scri ptedActi on class uses the 
BSF (Bean Scripting Framework) to enable Struts developers to create a 
Struts Action in the language of their choice, including JavaScript, Python, 
TCL, ActiveScript, and PerlScript. 

The Bean Scripting Framework is an open-source project supported by IBM. 
BDF can be used not only by the Struts Action Scripting plug-in, but with any 
Java application or applet to incorporate scripting. You can find it at 

www- 124. ibm.com/developerworks/projects/bsf 
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.alphaworks.ibm.com/tech/strutsscripting 
out more about Struts Action Scripting. 



StrutsDoc 



Would you like to see your Struts application configuration represented as a 
JavaDoc-like document? Then the StrutsDoc package is what you're looking 
for. StrutsDoc is an Ant task that generates the documentation from reading 
the struts -conf i g . xml file. (See ant .apache . org for further information 
on Ant.) StrutsDoc currently supports only the 1.1 version of Struts. 

See Figure 15-1 for a sample of the document. The sample is taken from the 
MusicCollection application created in Chapter 14. This package can create 
a useful form of documentation, especially for larger projects. We briefly 
explain Ant in the "Choosing Your Development Environment" section of 
Chapter 2. For more information, visit the Web site at 

struts. sourceforge.net/strutsdoc 



Figure 15-1: 

StrutsDoc 
view of the 
home 
Action. 
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Here is the Ant bui 1 d . xml file we used to generate the document shown in 
Figure 15-1. 



t name="musi ccol 1 ecti on" def aul t=" run-strutsdoc" 
basedi r = " . " > 

<taskdef name="strutsdoc" cl assname=" strutsdoc . Ma i n" 
cl asspath = " WEB- INF/1 i b/strutsdoc-0 . 4 . jar" /> 
<target name="run-strutsdoc"> 

<strutsdoc destdi r="api /struts" conf i gdi r="WEB-INF' 
webxml=" WEB- INF/web. xml "/> 

</ta rget> 
</project> 



StrutsTestCase far JUnit 

If you already use JUnit, StrutsTestCase for JUnit will be of immediate interest 
to you. If you don't currently use JUnit or have never heard of it, a little expla- 
nation is needed. JUnit is a popular testing framework for developing unit 
tests for Java code. It was developed by Erich Gamma and Kent Beck and 
is available as open-source software. JUnit is closely associated with the pro- 
gramming methodology called eXtreme Programming (XP). The underlying 
philosophy — eXtremely simplified! — is that you should write the tests for a 
class before you write the class itself. You can find more about JUnit and XP at 



www.junit.org/index. htm 









StrutsTestCase for JUnit is an extension of the standard JUnit TestCase class, 
which provides facilities for testing code based on the Struts framework. 
StrutsTestCase provides two approaches to running ActionServlet:a mock 
approach and an in-container approach. The mock approach runs the Struts 
ActionServlet without requiring a Web container. With the in-container 
approach, tests are run while running the Web container. Because StrutsTest 
Case uses the Acti onServl et controller to test your code, you can test not 
only the implementation of your Acti on objects, but also your mappings, form- 
beans, and forwards declarations. And because StrutsTestCase already provides 
validation methods, it's quick and easy to write unit test cases. 

For further information on StrutsTestCase for JUnit, visit their Web site at 

strutstestcase.sourceforge.net 



Stmts Workflow Extension 



The problem with Web applications is the ability of the user to do unusual 
actions that tend to screw up the natural flow of things. For example, suppose 



Chapter 15: Ten Helpful Extensions to Struts 



iorm, wni 

DropBodteS 

The Strut 



a user has just pressed the Reload button after he or she has submitted a 
form, which results in the form being submitted again. Another example might 
ming actions out of sequence through the creative use of the Back 
hese are real problems that Web application developers have to face. 
The Struts Workflow Extension deals these problems. 



The Struts Workflow Extension addresses these issues by doing the following: 

V Disallows the user to accidentally do double submits, such as by press- 
ing the browser's reload button. 

t<" Makes the user follow a prescribed sequence of steps when required. 

v 0 Supports the implementation of reusable action sequences. For exam- 
ple, you can display a confirmation dialog box when the user is about to 
delete something. 

Cleans up session attributes such as by removing session scope forms, 
when the user finishes or breaks out of a sequence of actions. 

Prevents the user from deviating from a sequence of actions. For exam- 
ple, you may want the user to answer a dialog box with only yes or no, 
not allowing any other option. 

The Struts Workflow Extension does not require the modification of any appli- 
cation classes, just the acti on definitions in the struts config.xml file. 
The Extension provides the workflow services by extending the Struts 

ActionMapping and RequestProcessor classes. 

The providers of this open-source solution did a great job providing thorough 
documentation to go with their product. To find out more, visit LivingLogic's 
Web site at 



www .livinglogic.de/Struts 



Eas^ Stmts Pluq-m 

Easy Struts is a plug-in for your development environment that promises to 
aid in the development process by providing a specialized editor for modify- 
ing the struts - confi g . xml file and various wizards to help you construct 
entries for the config file. Easy Struts is available as a plug-in for the Eclipse 
and JBuilder IDEs (Integrated Development Environments). 



The editor for the struts-config.xml is extensive, as shown in Figure 15-2. 
To download the plug-in, visit the Easy Struts Web site at 



easy struts. sourceforge. net 
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Figure 15-2: 

The Easy 
Struts plug- 
in editor for 
the Eclipse 
IDE. 



nv.i - struts confiij.xml - Eclipse Phitfoim 



File Edit Navigate Search Project Tomcat Run Window Help 



I 1.1 (default) 



The following elements a 
slruts-config xml : 

- gj form-beans 
| m 9 loginForm 

global-exceptions 

B global-forwards 
-. [&l action-mappings 
j (3 • /login 

ft controller 

^5 org. apache. struts.action. MESSAGE 



Easy Struts | Source 



Easy Struts editor vO.6.4 
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This editor help you to manage strut a- coring :;rnl files . select an element in Struts tree. 

- You can add/remove element with contextual menu on tree. 

- By double click on a class field, you can browse available classes in your project 

- By double click on a jsp field, you can browse available jsp files in your webapp. 

- Easy Struts Editor can write default value in your struts-config.xml, for this check 
the Easy Struts preferences. 

- Easy Struts Editor can check error concerning jsp, classes and required values, for 
this check the Easy Struts preferences. 

- Easy Struts Editor can generate classes from struts-config.xml. 

You can show/hide Struts tree in editor If the tree was hided, you can use the 
Easy Struts view to browse struts element 

You can also use Easy Struts view to browse your webapp document and descriptors. 

> Click here to show/hide tree 

> Click here to show Easy Struts View 

The followings wizards are available : 

> new Action +Form + JSP 

> new Action 

> new Form 

> new Forward 

> new Exception 

> new Datasource 
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In This Chapter 

The Struts Web site 

The Struts mailing lists 

Articles 

Tutorials 

Consultants 

Classes 

Training resources 
Sample applications 
The documentation 
Friends and colleagues 



MM /hen you're informed, you have a better chance of success in any pro- 
ww ject that you undertake. In this chapter, we provide some pointers to 
help you achieve success. Most of these resources are available on the Web, 
although some may be hard to find. The key to finding good information is 
in sifting the wheat from the chaff, so to speak. Luckily, we did the hard work 
for you. 



You should consider Jakarta. apache.org/struts / as the definitive source 
of information for Struts — the Struts portal. Here you can find the latest 
binary and source code for Struts, documentation, history, planned enhance- 
ments, bug reports, as well as many other resources. Be sure to click the 
Resources link under the Community heading for a long list of helpful article, 
tutorials and examples. 




Struts Web Site 
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into problems that you can't resolve by reading this book or by read- 
ing the documentation, the next place to go is to the Struts mailing lists. Mailing 
lists provide a forum for Struts users (developers who use Struts to build Web 
applications) to ask and answer development questions. Experienced Struts 
developers monitor the list and try to provide help and guidance. 

You can take advantages of the Struts Users mailing list in several ways. The 
first way is to search the mailing list archives at 

nagoya . apache . or g/eyebrowse/Summari zeLi st?l i stld=42 

to see whether your problem or question has already been answered. More 
than likely, it has. The second way is to join the Struts User mailing list (or 
the shorter mailing list digest that comes out once a day). To join the mailing 
list, go to 

jakarta . apache. org/si te/mai 1 2 . html #Struts 

When you become a member of the mailing list, you can post your question 
directly to the list. 

One disadvantage of joining the mailing list is the number of e-mails you 
receive. If you want to post messages without joining the mailing list, use the 
Struts newsgroup at 

www . beanbase . com 

An alternate site for examining mailing list archives is 

www . mai 1 -archive. com 



You may find this site useful if the Apache Web site is too slow or cumber- 
some. You can also search other mailing lists here. 

If you get to the point where you would like to contribute to the development 
of Struts by adding to the code base, documentation, or test cases, join the 
developers mailing list. You can join at 

Jakarta. apache. org/si te/mail 2. html#Struts 

The mailing list includes notifications each time source code is checked in. 

Do not use the developer's mailing list for questions or problems related to 
using Struts unless you want to incur the wrath of the developers on the list. 
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nge of articles are available for your edification and enjoyment. 
Many of these articles are written by the same people who helped develop 
the Struts framework. In this section, we list a few that we think are particu- 
larly interesting and useful. 

An interview by ServerSide.com with the Struts creator, Craig McClanahan, is 
particularly enlightening. You can select questions that were asked of Mr. 
McClanahan during the interview and see his responses in full-motion video. 
To see the interview, go to the following: 

www .theserverside. com/events/ videos/CraigMcClanahan/dsl/ 
i ntervi ew . html 

You should have a high-speed connection to take advantage of the video. 

Another good article is "Jakarta Struts: Seven Lessons from the Trenches" by 
Chuck Cavaness. In this article, Mr. Cavaness shares the best practices that 
he gleaned from developing Struts applications for his company. These valu- 
able lessons can save you a lot of development time and make your applica- 
tion more robust. You can read the article at 



www . on Java . com/p 


iib/a /on j av 


a/2002/10 


/30/jakarta . html 




You can find a long list of articles 
Web site at 


and presentations by visiting the Struts 


j a karta. apache. org/struts/ 


resources/a rticles. html 





Tutorials 

Several tutorials offer a step-by-step walkthrough of the process involved in 
building a Struts application. A fairly complete tutorial is offered by Stephen 
Weisner. This tutorial is in PDF format and has a well-organized table of con- 
tents. Go to 

rzserv2.fhnon. de/~l g002556/struts/Struts_Tutori al . pdf 

If you would like to try your hand at creating a Struts application that uses 
the iBATIS persistence mechanism, try the tutorial by Rick Reumann at 

www .reumann.net/do/struts/main 
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The application that you create in this tutorial is a little more real-world 
than most — you build the structure to input and retrieve information from 
e. 



When you consider yourself to be well-versed in Struts programming and 
lore, you can take a short quiz (just for fun) to test how detailed your knowl- 
edge is. You can find the quiz at 

developer. Java. sun. com/developer/Quizzes/misc/struts. html 

You can find a fairly diverse list of tutorials and examples at the Struts Web 
site, at 

Jakarta. apache. org/struts/resources/tutorials. html 



Consultants 

You can conduct an Internet search for "Struts Consultants" to find a list 
of consultants who have their shingles out on the Web. For another useful 
resource, look at StrutsProjectPages on the Apache Wiki Web site. (If you 
want to know what a Wiki is, see the "What's a Wiki?" sidebar.) You can find 
the Apache Wiki at 

nagoya.apache.org/wiki/apachewiki.cgi ? Home Page 



When you get to StrutsProjectPages, you can choose the StrutsConsultants 
link to get a list of Struts consultants by geographical location. 




Anyone can create a Web page claiming to be a Struts expert. If you're consid- 
ering hiring a consultant for help in developing a Web application, be sure to 
ask for references and examples of completed work. 



What's a wiki? 



According to the original wiki site at c2 . com/ 
cgi /wi ki, "Wiki is a composition system, it's 
a discussion medium, it's a repository, it's a mail 
system, it's a chat room, it's a tool for collabora- 
tion." It was originally called WikiWiki (Hawai- 
ian for quick). The first wiki site was established 
in 1995 at the link just mentioned. The creators 



of the open-source wiki software have a Web 
site at 

wiki .org/wiki . cgi ?Wel comeVi si tors 

Go there to read about their book. The Wiki 
Way, download the software, and find out more 
about wiki. 



Chapter 16: Ten Ways to Find More Information 



Classes 



ipBooks- 

develoDrru 



panies and individuals offer various levels of training in Struts 
development. A casual search on Google found 43,600 hits for the words 
"Struts training." You can choose from the various offering of companies in 
your geographical area. You might also find online training classes. 

Here are a couple of listings of companies that offer Struts training courses in 
the United States: 

f* Accelebrate at www .accelebrate. com/struts/ 

f Themis, Inc. at www . themi sine, com/courses/ index, asp? 
category]' d=34 

For a training company in Europe, you can go to 

www .sharedskills.com/softwaredev/strutscourse. html 
You can download a Struts training video for free at 

www. mi ddl ewa re-company. com /of fer/6may -thanks. shtml 
The Struts Web site lists several potential sources for training at 

j a karta. apache. org/struts/resources/seminars. html 



Stmts Resources Web Sites 



Because of the popularity of Struts, lots of developers are busy creating 
tools, add-ons, and other software to complement the Struts framework. We 
covered some of these packages in Chapter 15, but you can find many more. 
For a comprehensive list, go to 

Jakarta. apache. org/struts/resources/ext ens ions. html 

Many tools are also available to help the developer create Struts applica- 
tions. One such commercial tool is called Struts Studio from Exadel. Struts 
Studio is a plug-in that you use with the Eclipse development environment. 
Struts Studio offers a visual development environment for Struts applica- 
tions. Exadel offers several editions, including a free community version that 
runs as a stand-alone Java application. Although we have never used this 
tool, we are impressed with its potential time-saving features. The plug-in 
versions aren't free, but you should not let that be a deciding factor. If you 
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develop with Struts a lot, the time that you save with these tools could easily 
save your company a tidy sum of money in your salary alone. At least, that's 
ent you can use with your boss. You can look at the product 
ion or download it at 



www. exadel . com/products_strutsstudi o . htm 

We discussed the Sysdeo Tomcat Launcher plug-in Chapter 2. Nevertheless, 
we remind you that this Eclipse plug-in is extremely useful. You can find it at 

www .sysdeo.com/eclipse/tomcatPlugin.html. 

The following page has a comprehensive list of plug-ins and standalone tools 
to use with Struts: 



Jakarta. apache. org/struts/resources/tools. html 

If you're using the Eclipse development environment, several plug-ins, while 
not directly related to Struts, make Struts development easier. For example, 
having an XML plug-in makes it easier to edit web . xml and struts -confi g . 
xml files. In addition, many external frameworks that can be used with Struts 
have Eclipse plug-ins for easier use. The primary site that we recommend to 
search for Eclipse plug-ins is 

eel ipse-plugins.2y. net/eel ipse/ 

The site has organized the plug-ins into various categories that make it easy 
to find the ones that are of interest. 



Sample Applications 

What better way to understand Struts that to look at example applications 
built on Struts? You get a chance to look through the code and see how other 
programmers have used the Struts features. Most example applications are 
simple enough that you won't have to invest a long time trying to understand 
what they're trying to do. 

The Struts binary download comes complete with the struts-example 
application. To run this application, just drag the struts example.war file 
from the Jakarta - struts -1.1/ we bapps folder into the Tomcat/webapps 
folder. You can access the application through the following URL: 

http: //local host/struts -example 

You can read the description of the application by clicking the A Walking 
Tour of the Example Application link. This example application is based on 
Struts 1.0. You can find an interesting cross-referenced listing of files used in 
the example application at 
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www. projectrefinery.com/StrutsCrossReference.pdf 

wide range of sample and example Struts applications, look at 

sourceforge. net/pro ject/showfiles . php?group_i d=49385 



Many of the applications provide examples of how to integrate other frame- 
works (such as Velocity, Cocoon, or Hibernate) into a Struts application. You 
won't find a lot a lot of documentation explaining the application. However, 
if you download the project, additional documentation may be included with 
the download. Another sourceforge site that has a variety of sample Struts 
applications is 

struts. sourceforge. net 

Finally, the Struts Web site offers its own list of sample applications. You can 
find the sample application list at 

Jakarta. apache. org/struts/resources/examples. html 



Stmts Documentation 

The Struts documentation is better than most open-source documentation. This 
material is essentially a local copy of the Struts Web site. The documentation is 
provided as a Struts application called struts -documentati on . wa r. To install 
struts-documentation .war, simply copy it from the jakarta-struts-1 . 1/ 
webapps folder to the Tomcat/webapps folder. Almost everything that you 
find at the live Web site can be found also in the struts -documentati on 
application. You can access the application through the following URL: 

http : //l oca! host/struts -documentati on 

The User and Developer Guides link on the home page provides an overview 
of the architecture of Struts with some insights into the historical back- 
ground of the project. Some readers might find Chapter 6, "Getting Started," 
of particular interest. You can also find useful information on installing Struts 
on a variety of Web containers. In addition, the section on "Release Notes" 
can provide insight into the evolution of the product. 

The FAQs and HowTos link on the Struts home page provides additional help 
on getting started with Struts, as well as instructions on several Struts usage 
topics not covered in the main documentation. 
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the best resource you can find is closer than you think. Friends who 
are in the programming business as well as the other programmers you work 
with may already have experience with Struts. Nothing is better than being 
able to talk face-to-face with someone who knows more than you do (at least 
about Struts). For that matter, even if someone is less experienced with Struts 
than you are, discussing issues and questions with a like-mined person can 
stimulate the creative and problem solving processes. Who knows what solu- 
tions you can create? 
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In this part . . . 

J\ ppendix A lists all the Struts and JSTL tag libraries, 
v » what they do, and their syntax. This appendix is a 
great reference to help you find the tag that you need, 
when you need it. Appendix B is a glossary to help you 
with some of the more obscure terms that Struts and Java 
programmers use. 













Appendix A 
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Library Syntax 



7ags from the Struts-EL and JSTL tag libraries are used throughout this 
book during discussing the creation of JSP pages. This appendix provides 
the complete syntax for each of the tags in the libraries. This material appears 
courtesy of and is copyrighted by Sun Microsystems, Inc. 

Struts-EL and JSTL libraries actually consist of numerous separate libraries, 
each organized according to function. Struts-EL has the Beans-EL, HTML-EL, 
and Logic-EL libraries. JSTL consists of the Core, Formatting, SQL, and XML 
libraries. 



Beans-EL Library Syntax 

The Beans-EL library provides tags for defining and using beans available to 
the JSP page. 

<bean:message> Renders an internationalized message string to the response. 

<bean:message [argO="message argument 0"] 

[argl="message argument 1"] 

[arg2="message argument 2"] 

[arg3="message argument 3"] 

[bundl e="resourceBundl e"] 

[key="messageKey"] 

[locale="localeBean"] 

[natne="beanName"] 

[property= "property Name"] 

[scope=" (page | request | session | appl ication} "]/> 

<bean:page> Exposes a specified item from the page context as a bean. 

<bean:page id="variableName" 

property-" {confi g | response | request | sessi on | appl i cat i on) "/> 
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<bean:resource> Loads a Web application resource and makes it available as 
a bean. 
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isource i d=" va ri abl eName" 
FesourceName" 
[input="anyValue"]/> 

<bean:size> Defines a bean containing the number of elements in a Collection 
or Map. 

<bean:size i d=" va r i abl eName " 

[col 1 ecti on="theCol 1 ecti on"] 

[name="beanName"] 

[property="propertyName"] 

[scope=" (page | request | session | appl i cation ) "]/> 

<bean:struts> Exposes a named Struts internal configuration object as a bean. 

<bean:struts i d=" va r i abl eName " 
[f ormBean="acti on Form"] 
[forward="acti on Forward"] 
[mapping="actionMapping"]/> 



HTML-EL Library Syntax 

The HTML-EL library can create Struts forms as well as most of the HTML 
tags used in generating a user interface. 

<html:base> Renders (generates) an HTML <base> element. 

<html :base [target="windowTarget"] 
[server="serverName"]/> 

<html:button > Renders a Button Input field. 

<html :button property="requestParamName" 
[accessKey="keyboardChar"] 
[alt="altTextString"] 
[altKey="altResourceKey"] 
[disabled="{true|false)"] 
[i ndexed=" { true | fal se ( " ] 
[onbl ur="JavaScri pt function"] 
[onchange="JavaScri pt functi on"] 
[oncl i ck="JavaScri pt functi on"] 
[ondbl cl i ck="JavaScri pt functi on"] 
[onfocus="JavaScri pt functi on"] 
[onkeydown="JavaScri pt functi on"] 
[onkeypress="JavaScri pt functi on"] 
[onkeyup="JavaScri pt functi on"] 
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[onmousedown="JavaScri pt functi on"] 
[£nmousemove=" JavaScri pt functi on"] 
out=" JavaScri pt function"] 
iOver="JavaScri pt function"] 
[onmouTeup=" JavaScri pt functi on"] 
[s ty 1 e=" cssSty 1 e " ] 
[styleClass="cssClass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[ti tl e="advi soryTi tl e" ] 
[title Key= " advi soryTi tl eKey"] 
[value="label"]/> 



<html:cancel> Renders a Cancel button. 



<html :cancel [accessKey="keyboardChar"] 
[alt="altTextString"] 
[al tKey="al tResourceKey"] 
[disabl ed=" I true | fal se) "] 
[onbl ur=" JavaScri pt function"] 
[onchange=" JavaScript functi on"] 
[oncl i ck=" JavaScri pt functi on"] 
[ondbl cl ick=" JavaScri pt functi on"] 
[onfocus=" JavaScri pt functi on"] 
[onkeydown=" JavaScri pt functi on"] 
[onkeypress=" JavaScript function"] 
[on key up=" JavaScri pt functi on"] 
[onmousedown=" JavaScri pt functi on"] 
[onmousemove-" JavaScri pt functi on"] 
[onmouseout=" JavaScri pt functi on"] 
[onmouseover=" JavaScri pt functi on"] 
[onmouseup=" JavaScri pt functi on"] 
[ proper ty=" request Pa ramName"] 
[style="cssStyle"] 
[styleClass="cssClass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[title="advisoryTitle"] 
[ti tl eKey="advi soryTi tl eKey"] 
[val ue="l abel "]/> 



<html:checkbox> Renders a Checkbox input field. 



<html :checkbox property="requestParamName" 

[access Key="keyboardChar"] 

[alt="altTextString"] 

[a 1 1 Key=" a 1 tResourceKey " ] 

[disabled="|true|false)"] 

[i ndexed=" { true | fal se } " ] 

[name="beanName"] 

[onbl ur="JavaScri pt function"] 

[onchange=" JavaScri pt functi on"] 

[oncl i ck=" JavaScri pt functi on"] 
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[ondbl cl i ck=" JavaScri pt fundi on"] 
[£infocus="JavaScript functi on"] 
wn="JavaScri pt function"] 
iess="JavaScri pt function"] 
[onkeyUp=" JavaScri pt functi on"] 
[onmousedown=" JavaScri pt functi on"] 
[onmousemove-" JavaScri pt functi on"] 
[onmouseout=" JavaScri pt functi on"] 
[onmouseover=" JavaScri pt functi on"] 
[onmouseup=" JavaScri pt functi on"] 
[s ty 1 e=" cssSty 1 e" ] 
[styleClass="cssClass"] 
[styl eld=" identi fi er" ] 
[tabindex="taborder"] 
[title="advisoryTitle"] 
[ti tl eKey="advi soryTi tl eKey"] 
[val ue="val ueTransmi tted"]/> 



<html:errors> Conditionally displays a set of accumulated error messages. 



<html :errors [bundle="messageResource"] 
[locale="localeKey"] 
[name="acti on Errors Key"] 
[property=" act i on Errors Property"]/) 



<html:Hle> Renders a File Select input field. 

<html :file property="requestParamName" 
[accessKey="keyboardChar"] 
[accept="contentTypes"] 
[alt="altTextString"] 
[al tKey=" a 1 tResourceKey"] 
[disabled-" {true| false) "] 
[i ndexed=" ( true | fal se I " ] 
[maxl ength="maxCharsToAccept"] 
[name="beanName"] 
[onbl ur="JavaScri pt function"] 
[onchange=" JavaScri pt functi on"] 
[oncl i ck=" JavaScri pt functi on"] 
[ondbl cl ick=" JavaScri pt functi on"] 
[onfocus=" JavaScri pt functi on"] 
[onkeydown=" JavaScri pt functi on"] 
[onkeypress=" JavaScri pt functi on"] 
[onkeyup=" JavaScri pt functi on"] 
[onmousedown=" JavaScri pt functi on"] 
[onmousemove-" JavaScri pt functi on"] 
[onmouseout=" JavaScri pt functi on"] 
[onmouseover=" JavaScri pt functi on"] 
[onmouseup=" JavaScri pt functi on"] 
[si ze="si zeOf Fi 1 eSel ecti onBox"] 
[style="cssStyle"] 
[styleClass="cssClass"] 
[styleld="identifier"] 
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[tabi ndex="taborder"] 
[Jitle="advisoryTitle"] 

y="advisoryTitleKey"] 
fieldValue"]/) 



<html:form> Defines an Input Form element. 



<html :form acti on="URL" 

[enctype="encoding"] 

[focus="fieldName"] 

[focusIndex="indexInGroup"] 

[method="httpMethod"] 

[name="actionForm"] 

[onreset="JavaScri pt functi on"] 

[onsubmi t=" JavaScri pt functi on"] 

[styl e="cssStyl e"] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[target="windowTarget"]/> 



<html:frame> Renders an HTML frame element. 



<html :frame [action="actionName"] 

[anchor="anchorTag"] 

[forward="forwardName"] 

[f rameborder=" (0 1 1 ) "] 

[f rameNa[ne="f rameName"] 

[href="URL"] 

[1 ongdesc="l ongDescripti onURI "] 

[marginheight="marginHeight Pixels"] 

[ma rg i nwidth= "ma rginWidth Pixels"] 

[name="beanName"] 

[noresize="|true|false)"] 

[page="transferPath"] 

[ pa rami d=" request Pa ram"] 

[paramName="beanName"] 

[ pa ramProperty=" bean Property"] 

[paramScope="page| request | session | appl ication"] 

[property="beanProperty"] 

[scope="page request | sessi on | appl i cat i on"] 

[scrol 1 i ng=" {yes | no | auto) "] 

[style="cssStyle"] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[title="advisoryTitle"] 

[ti tl eKey="advi soryTi tl eKey"] 

[transact! on=" ( true I false}"]/) 



<html:hidden> Renders a Hidden field. 



<html : hi dden property="inputFieldName" 
[access Key="keyboardChar"] 
[alt="altTextString"] 
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[altKey="al tResourceKey"] 
[jndexed="{true|false)"] 
eanName"] 

"JavaScript function"] 
[onchaTge="JavaScri pt functi on"] 
[oncl i ck="JavaScri pt functi on"] 
[ondbl cl i ck="JavaScri pt functi on"] 
[onfocus="JavaScri pt functi on"] 
[onkeydown="JavaScri pt functi on"] 
[onkeypress="JavaScri pt functi on"] 
[onkeyup="JavaScri pt functi on"] 
[onmousedown="JavaScri pt functi on"] 
[onmousemove="JavaScri pt functi on"] 
[onmouseout=" JavaScript functi on"] 



[onmouseover="JavaScri pt function' 

[onmouseup="JavaScri pt functi on"] 

[style="cssStyle"] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[title="advisoryTitle"] 

[ti tl eKey="advi soryTi tl eKey"] 

[value="fieldValue"] 

[write=" ( true I fal sel "]/> 



<html:html> Renders an HTML <html > element. 



<html : html [xhtml =" {true I f al se) " ]/> 



<html:image> Renders an input tag of type image. 



<html :image [accessKey="keyboardChar"] 
[al t="al tTextString"] 
[al tKey=" a 1 tResourceKey"] 
[border="borderWidth"] 
[bundle="resourceBundle"] 
[disabled="|true|false)"] 
[i ndexed=" {true | fal se ( " ] 
[locale="locale"] 
[onbl ur="JavaScri pt function"] 
[onchange="JavaScri pt functi on"] 
[oncl i ck="JavaScri pt functi on"] 
[ondbl cl i ck="JavaScri pt functi on"] 
[onf ocus="JavaScri pt functi on"] 
[onkeydown="JavaScri pt functi on"] 
[onkeypress="JavaScri pt functi on"] 
[onkeyup="JavaScri pt functi on"] 
[onmousedown="JavaScri pt functi on"] 
[onmousemove="JavaScri pt functi on"] 
[onmouseout="JavaScri pt functi on"] 
[onmouseover="JavaScri pt functi on"] 
[onmouseup="JavaScri pt functi on"] 
[page="imagePath"] 
[pageKey="imagePathKey"] 
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[property="propertyName"] 
[^ rc=" i mageURL" ] 

"imageURLKey"] 
cssStyle"] 
[styl eTl ass="cssCl ass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[ti tl e="advi soryTi tl e" ] 
[ti tl eKey="advi soryTi tl eKey"] 
[val ue="val ueSubmitted"]/) 



<html:img> Renders an HTML i mg tag. 



<html : img [al i gn=" (1 eft | ri ght | top | middl e | bottom texttop | a bsmi ddl e | a bs bottom) "] 

[al t="al tTextString"] 

[al tKey=" a 1 tResourceKey"] 

[border="borderWidth"] 

[bundle="resourceBundle"] 

[height="imageHeight"l 

[hspace=" horizontal Space"] 

[imageName="l ocal Name"] 

[ismap="serverSideMap"] 

[1 ocal e="l ocal e"] 

[name="beanName"] 

[oncl i ck="JavaScri pt functi on"] 

[ondbl cl i ck=" JavaScript function"] 

[onkeydown="JavaScri pt functi on"] 

[onkeypress="JavaScri pt functi on"] 

[onkeyup="JavaScri pt functi on"] 

[onmousedown="JavaScri pt functi on"] 

[onmousemove="JavaScri pt functi on"] 

[onmouseout="JavaScri pt functi on"] 

[onmouseover="JavaScri pt functi on"] 

[onmouseup="JavaScri pt functi on"] 

[ pa rami d=" request Pa ram"] 

[page="imagePath"] 

[pageKey="imagePathKey"] 

[paramName="beanName"] 

[ pa ramProperty=" bean Property"] 

[paramScope="page request | sessi on | appl i cat i on"] 

[property="propertyName"] 

[scope="page request | sessi on | appl i cat i on"] 

[s rc=" i mageURL" ] 

[srcKey=" imageURLKey"] 

[style="cssStyle"] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[ti tl e="advi soryTi tl e" ] 

[ti tl eKey=" advi soryTi tl eKey"] 

[useMap="mapName"] 

[vspace="verti cal Space"] 

[width="imageWidth"]/> 
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<html:javascript> Renders JavaScript validation based on the validation rules 
loaded by the Validator plug-in. 



ivascript [cdata=" {true | fal se) "] 
cJavascri pt=" ( true | false}"] 
[formName="formName"] 
[method="al tJavaScri ptMethod"] 
[page="currentPage"] 
[src="value"] 

[stati cJavascri pt=" ( true | fal se) "] 
[htmlComment=" ( true I false}"]/) 



<html:link> Renders an HTML anchor or hyperlink. 



<html :link [accessKey="keyboardChar"] 
[action="actionName"] 
[anchor="anchorTag"] 
[forward="forwardName"] 
[href="URL"] 

[i ndexed=" {true | fal se ) " ] 
[indexId="indexName"] 
[1 inkName="anchorName"] 
[name="beanName"] 
[onbl ur="JavaScri pt function"] 
[oncl i ck="JavaScri pt functi on"] 
[ondbl cl i ck="JavaScri pt functi on"] 
[onf ocus="JavaScri pt functi on"] 
[onkeydown="JavaScri pt functi on"] 
[onkeypress="JavaScri pt functi on"] 
[onkeyup="JavaScri pt functi on"] 
[onmousedown="JavaScri pt functi on"] 
[onmousemove="JavaScri pt functi on"] 
[onmouseout="JavaScri pt functi on"] 
[onmouseover="JavaScri pt functi on"] 
[onmouseup="JavaScri pt functi on"] 
[page="transferPath"] 
[pa rami d=" request Pa ramName"] 
[paramName="beanName"] 
[ pa ramProperty=" bean Property"] 
[paramScope=" { page | request | sessi on | appl i cat i on) "] 
[property="propertyName"] 
[scope=" {page | request | sessi on | appl i cat i on ) "] 
[style="cssStyle"] 
[styleClass="cssClass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[target="wi ndowTarget"] 
[title="advisoryTitle"] 
[ti tl eKey="advi soryTi tl eKey"] 
[transacti on=" f true | false}"]/) 
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ssages id="beanName" 
"resourceBundle"] 
"localeBean"] 
[name="messagesBeanName"] 
[ pr ope rty=" property Name"] 
[header="headerKey"] 
[footer="footerKey"] 
[message=" ( true I false) "]/> 



<html:multibox> Renders a Checkbox input field. 



<html :multibox property="requestParamName" 

[accessKey="keyboardChar"] 

[alt="altTextString"] 

[al tKey="al tResourceKey"] 

[disabled="|true|false)"] 

[name="beanName"] 

[onbl ur="JavaScri pt function"] 

[onchange=" JavaScript functi on"] 

[oncl i ck=" JavaScri pt functi on"] 

[ondbl cl i ck=" JavaScri pt functi on"] 

[onfocus="JavaScri pt functi on"] 

[ on keydown=" JavaScri pt functi on"] 

[onkeypress=" JavaScript functi on"] 

[on key up=" JavaScri pt functi on"] 

[onmousedown=" JavaScri pt functi on"] 

[onmousemove=" JavaScri pt functi on"] 

[onmouseout=" JavaScri pt functi on"] 

[onmouseover=" JavaScri pt functi on"] 

[onmouseup=" JavaScri pt functi on"] 

[styl e="cssStyl e" ] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[tabindex="taborder"] 

[title="advisoryTitle"] 

[ti tl eKey="advi soryTi tl eKey"] 

[value="valueTransmitted"]/> 



<html:option > Renders a Select Option. 

<html : opti on value="valueSubmitted" 

[bundl e="resourceBundl e"] 

[disabled="{true|false)"] 

[key="messageKey"] 

[locale="localeBean"] 

[style="cssStyle"] 

[styleClass="cssClass"] 

[styleId="identifier"]/> 
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<html:options> Renders a Collection of Select Options. 
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tions [col 1 ecti on="beanName"] 
[true | false}"] 
e=" 1 a bel Bean " ] 
[1 abel Property-" 1 abel Property"] 
[name="beanName"] 
[ pr ope rty=" bean Property"] 
[style="cssStyle"] 
[styl eClass="cssCl ass "]/> 



<html:optionsCollection> Renders a Collection of Select Options (more con- 
sistently than the <html : opti ons> tag). 



<html : opt i onsCol 1 ecti on [fi lter=" {true | false}"] 
[label="beanProperty"] 
[name="beanName"] 
[property="formBeanProperty"] 
[style="cssStyle"] 
[styl eCl ass="cssCl ass"] 
[val ue="beanProperty"]/> 

<html:password> Renders a Password input field. 



<html :password property="requestParamName" 

[accessKey="keyboardChar"] 

[al t = " a 1 tTextString"] 

[al tKey=" a 1 tResourceKey"] 

[di sabl ed=" ) true | fal se} "] 

[i ndexed=" {true | fa 1 se } " ] 

[maxl ength="maxInputChars"] 

[name="beanName"] 

[onbl ur="JavaScri pt function"] 

[ onchange=" JavaScri pt functi on"] 

[oncl i ck="JavaScri pt functi on"] 

[ondbl cl i ck=" JavaScri pt functi on"] 

[onf ocus="JavaScri pt functi on"] 

[onkeydown=" JavaScri pt function"] 

[onkeypress=" JavaScri pt functi on"] 

[onkeyup=" JavaScri pt functi on"] 

[onmousedown=" JavaScri pt functi on"] 

[onmousemove-" JavaScri pt functi on"] 

[onmouseout=" JavaScri pt functi on"] 

[onmouseover=" JavaScri pt functi on"] 

[onmouseup=" JavaScri pt functi on"] 

[readonly-" {true | fal se) "] 

[redisplay-"! true | false)"] 

[styl e="cssStyl e"] 

[styl eCl ass="cssCl ass"] 

[styleld="identifier"] 

[si z e = " a 1 1 ocatedlnputChars"] 
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[tabi ndex="taborder"] 
[Jitle="advisoryTitle"] 

y="advisoryTitleKey"] 
label"]/) 



<html:radio> Renders a Radio button input field. 



<html : radio val ue="tagVal ue" 

[accessKey="keyboardChar"] 

[al t="al tTextStri ng" ] 

[al tKey="al tResourceKey"] 

[disabl ed=" (true | false}"] 

[idName="beanName"] 

[indexed=" {true | fal se ) " ] 

[name="beanName"] 

[onbl ur="JavaScri pt function"] 

[onchange="JavaScri pt functi on"] 

[oncl i ck="JavaScri pt functi on"] 

[ondbl cl i ck=" JavaScri pt functi on"] 

[onfocus="JavaScri pt functi on"] 

[onkeydown=" JavaScri pt functi on"] 

[onkeypress=" JavaScri pt functi on"] 

[onkeyup=" JavaScri pt functi on"] 

[onmousedown=" JavaScri pt functi on"] 

[onmousemove-" JavaScri pt functi on"] 

[onmouseout=" JavaScript function"] 

[onmouseover=" JavaScri pt functi on"] 

[onmouseup=" JavaScri pt functi on"] 

[style="cssStyle"] 

[styleClass="cssClass"] 

[styleld="identifier"] 

[tabindex="taborder"] 

[title="advisoryTitle"] 

[ti tl eKey=" advi soryTi tl eKey"]/> 



<html:reset> Renders a Reset button input field. 



<html :reset [accessKey="keyboardChar"] 
[al t="al tTextString"] 
[al tKey="al tResourceKey"] 
[disabled="|true|false)"] 
[onbl ur=" JavaScri pt function"] 
[onchange=" JavaScri pt functi on"] 
[oncl i ck=" JavaScri pt functi on"] 
[ondbl cl i ck=" JavaScri pt functi on"] 
[onf ocus=" JavaScri pt functi on"] 
[onkeydown=" JavaScri pt functi on"] 
[onkeypress=" JavaScri pt functi on"] 
[onkeyup=" JavaScri pt functi on"] 
[onmousedown=" JavaScri pt functi on"] 
[onmousemove-" JavaScri pt functi on"] 
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[onmouseout="JavaScri pt functi on"] 
[Dnmouseover="JavaScri pt functi on"] 
[|y«o*sflup="JavaScri pt function"] 
[j^P4^fcy="inputFieldName"] 

[style="cssStyle"] 
[styleCl ass="cssCl ass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[title="advisoryTitle"] 
[ti tl eKey="advi soryTi tl eKey"] 
[value="label"]/> 

<html:rewrite> Renders a URI. 

<html :rewrite [action="actionName"] 
[anchor="anchorTag"] 
[forward="forwardName"] 
[href="URL"] 
[name="beanName"] 
[page="transferPath"] 
[pa rami d=" request Pa ramName"] 
[paramName="beanName"] 
[ pa ramProperty=" bean Property"] 
[paramScope=" I page | request | sessi on | appl i cati on) "] 
[ pr ope rty=" property Name"] 
[scope=" {page | request | sessi on | appl icat ion ) "] 
[transacti on=" { true | false) "]/> 

<html:select> Renders a Select element. 

<html :select property="requestParamName" 
[alt="altTextString"] 
[al tKey="al t Resource Key"] 
[disabled-" {true| false) "] 
[indexed="(true|false)"] 
[multiple="anyValue"] 
[name="beanName"] 
[onbl ur=" JavaScript functi on"] 
[onchange="JavaScri pt functi on"] 
[oncl i ck="JavaScri pt functi on"] 
[ondbl cl i ck="JavaScri pt functi on"] 
[onfocus="JavaScri pt functi on"] 
[onkeydown="JavaScri pt functi on"] 
[onkeypress="JavaScri pt functi on"] 
[onkeyup="JavaScri pt functi on"] 
[onmousedown="JavaScri pt functi on"] 
[onmousemove="JavaScri pt functi on"] 
[onmouseout="JavaScri pt functi on"] 
[onmouseover="JavaScri pt functi on"] 
[onmouseup="JavaScri pt functi on"] 
[style="cssStyle"] 
[styleClass="cssClass"] 
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[styl eld="identi fi er" ] 
[Jitle="advisoryTitle"] 

y="advisoryTitl eKey " ] 
tagVal ue"]/> 



<html:submit> Renders a Submit button. 



<html :submit [accessKey="keyboardChar"] 

[alt="altTextString"] 

[altKey="altResourceKey"] 

[disabl ed=" { true | fal se) "] 

[indexed="true| false) "] 

[onbl ur="JavaScri pt function"] 

[onchange="JavaScri pt functi on"] 

[oncl i ck=" JavaScri pt functi on"] 

[ondbl cl i ck=" JavaScri pt functi on"] 

[onfocus="JavaScri pt functi on"] 

[ on keydown=" JavaScri pt functi on"] 

[onkeypress=" JavaScri pt functi on"] 

[onkeyup=" JavaScri pt functi on"] 

[onmousedown=" JavaScri pt functi on"] 

[onmousemove=" JavaScri pt functi on"] 

[onmouseout=" JavaScri pt functi on"] 

[onmouseover=" JavaScri pt functi on"] 

[onmouseup=" JavaScri pt functi on"] 

[ proper ty=" request Pa ramName"] 

[styl e="cssStyl e" ] 

[styleClass="cssClass"] 

[styl eld=" i denti fi er " ] 

[tabindex="taborder"] 

[title="advisoryTitle"] 

[ti tl eKey=" advi soryTi tl eKey"] 

[value="label "]/> 



<html:text> Renders an input field of type Text. 



<html :text property-" i nputFi el dName" 
[access Key="keyboardChar"] 
[al t="al tTextString"] 
[al tKey=" a 1 tResourceKey"] 
[disabled="|true|false)"] 
[ i ndexed=" ( t r ue | f a 1 se ) " ] 
[maxlength="maxInputChars"] 
[name="beanName"] 
[onbl ur="JavaScri pt function"] 
[onchange=" JavaScri pt functi on"] 
[oncl i ck=" JavaScri pt functi on"] 
[ondbl cl i ck=" JavaScri pt functi on"] 
[onf ocus=" JavaScri pt functi on"] 
[onkeydown=" JavaScri pt functi on"] 
[onkeypress=" JavaScri pt functi on"] 
[ on keyup=" Java Script functi on"] 
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■"JavaScript function"] 
■"JavaScript function"] 
"JavaScript function"] 



iOver="JavaScript function" 
[onmouTeup="JavaScri pt functi on"] 
[readonly-" I true | false) "] 
[si ze="al 1 ocatedlnputChars"] 
[sty 1 e=" cssSty 1 e" ] 
[styleClass="cssClass"] 
[styleld="identifier"] 
[tabindex="taborder"] 
[title="advisoryTitle"] 
[titl eKey="advi soryTi tl eKey"] 
[value="initValue"]/> 



'] 



<html:textarea> Renders a Textarea element. 



<html :textarea property="inputFieldName" 
accessKey="keyboardChar"] 
alt="altTextString"] 
altKey="altResourceKey"] 
col s="numCol sDi spl ayed"] 
disabled="(true|false)"] 
indexed="{true|false)"] 
maxlength="maxInputChars"] 
name="beanName"] 
onbl ur="JavaScri pt function"] 
onchange=" JavaScript functi on"] 
oncl i ck="JavaScri pt function"] 
ondbl cl ick="JavaScri pt functi on"] 
onfocus="JavaScri pt function"] 
onkeydown="JavaScri pt functi on"] 
onkeypress="JavaScri pt functi on"] 
onkeyup="JavaScri pt function"] 
onmousedown="JavaScri pt functi on"] 
onmousemove="JavaScri pt functi on"] 
onmouseout="JavaScri pt functi on"] 
onmouseover="JavaScri pt functi on"] 
onmouseup="JavaScri pt functi on"] 
readonly-" j true | fal se) "] 
rows="numRowsDispl ayed"] 
sty 1 e=" cssSty 1 e" ] 
styl eCl ass="cssCl ass"] 
styleld="identifier"] 
tabindex="taborder"] 
title="advisoryTitle"] 
ti tl eKey="advi soryTi tl eKey"] 
value="initValue"]/> 



<html:xhtml > Renders HTML tags as XHTML. 

<html : xhtml/) 
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Loqic-EL Library Syntax 



c-EL library consists of tags useful for conditionally generating the 
page text. 

<logic:forward> Forwards control to the page specified by the Action 
Forward entry in the name attribute. 

<1 ogi c:forward name="f orwardName"/) 

<logic:iterate> Repeats the nested body content of this tag over a specified 
collection. 

<1 ogi c : i terate id="beanName" 
[col 1 ecti on="Col 1 ection"] 
[indexId="beanName"] 
[1 ength="maxNumEntri es"] 
[name="beanName"] 
[of fset=" start i ngPoi nt"] 
[property="propertyName"] 
[scope=" {page | request | session | appl i cat i on ) "] 
[type="javaCl assName"]/) 



<logic:match> Evaluates the nested body content of this tag if the specified 
value is an appropriate substring of the requested variable. 



<1 ogi c: match [cookie="cooki eName"] 

[header="headerName"] 

[1 ocati on=" (start | end) "] 

[name="beanName"] 

[parameter "request Pa ram"] 

[property="propertyName"] 

[scope=" {page | request | sessi on | appl i cati on ) "] 

[value="constant"]/> 



<logic:messagesNotPresent> Generates the nested body content of this tag if 
the specified message is not present in this request. 



<1 ogi c: mess ages Not Present [name="messageKey"] 

[property="propertyName"l 

[message=" { true | false}"]/) 



<logic:messagesPresent> Generates the nested body content of this tag if the 
specified message is present in this request. 



<1 ogi c: mess ages Present [name="messageKey"] 

[property="propertyName"] 

[message=" { true | false}"]/) 
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<logic:notMatch> Evaluates the nested body content of this tag if the speci- 
fied value is not an appropriate substring of the requested variable. 



otMatch [cookie="cookieName"] 
"headerName"] 
[location-" (start | end) "] 
[name="beanName"] 
[ pa rameter=" request Pa ram"] 
[property="propertyName"] 
[scope=" {page | request | sessi on | appl i cati on ) "] 
[value="constant"]/> 



<logic:notPresent> Generates the nested body content of this tag if the speci- 
fied value is not present in this request. 



<1 ogic: not Present [cooki e=" cooki eName"] 

[header="headerName"] 

[name="beanName"] 

[ pa rameter=" request Pa ram"] 

[property-" property Name"] 

[role="securityRole"] 

[scope=" {page | request | sessi on | appl i cati on ) "] 
[user="userName"]/> 



<logic:present> Generates the nested body content of this tag if the specified 
value is present in this request. 



<1 ogic: present [ cooki e=" cooki eName"] 

[header=" headerName"] 

[name="beanName"] 

[ pa rameter=" request Pa ram"] 

[property="propertyName"] 

[ rol e=" secur i ty Rol e " ] 

[scope=" {page | request | sessi on | appl i cati on ) "] 
[user="userName"]/> 



<logic:redirect> Renders an HTTP Redirect. 

<1 ogi c: redi rect [anchor="anchorTag"] 

[f orward="forwardName"] 

[href="URL H ] 

[name="beanName"] 

[page="transferPath"] 

[pa rami d=" request Pa ramName"] 

[paramName="beanName"] 

[ pa ramProperty="bean Property"] 

[paramScope=" ( pa ge | request | session | appl i cati on) "] 

[ pr ope rty=" property Name"] 

[scope=" {page | request | sessi on | appl i cati on) "] 

[transacti on=" ( true I false}"]/) 
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JSTL Core Library Syntax 



library provides the basic functionality needed to handle common 
JSP page: outputting text, manipulating beans, logical operations, 
flow control, and managing URL resources. The syntax for all the JSTL libraries 
was taken from Sun Microsystems JSTL specification document, version 1.0 
dated June 2002. 

<c:out> Evaluates an expression and outputs the result to the current 
JspWriter object. 

Syntax 1: Without a body. 



<c:out val ue="val ue" 
[escapeXml=" {true fal se ) "] 
[default="defaultValue"l /> 






Syntax 2: With a body. 






<c:out val ue="val ue" [escapeXml=" 
default value 

</c:out> 


(true false)" 


]> 




<c:set> Sets the value of a scoped variable or the property of a target object. 


Syntax 1: Set the value of a scoped variable using the attribute va 


1 ue. 


<c:set val ue="val ue" var="varName" 

[scope=" { page | request session appl i cati on) "]/> 




Syntax 2: Set the value of a scoped variable using body content. 




<c:set var="varName" [scope="{pag 

body content 

</c:set> 


e request ses si on appl i cati on) "]> 





Syntax 3: Set the property of a target object using the attribute value. 
<c:set val ue="val ue" target="target" property="propertyName"/> 

Syntax 4: Set a property of a target object using body content. 

<c:set target="target" property="propertyName"> 

body content 

</c:set> 

<c:remove> Removes a scoped variable. 

<c: remove var="varName" [scope=" (page request session | appl i cati on) "]/> 
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<c:catch> Catches ajava.lang.Throwable thrown by any of its nested 
actions. 
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[var="varName"]> 
'enactions 

</c:catch> 

<c:if> Evaluates the body content if the expression specified with the test 
attribute is true. 

Syntax 1: Without body content. 

<c:if test="testCondition" \iar="varName" [scope=" ( page | request | sessi on | 
application)"]/) 

Syntax 2: With body content. 

<c:if test=" testCondi tion" [var=" varName"] 

[scope=" {page | request | sessi on | appl i cati on ) "]> 

body content 
</c:if> 

<c:choose> Provides the context for mutually exclusive conditional execution. 

<c:choose> ^ 
body content (<when> and (otherwi se> subtags) 
</c:choose> 

<c:when> Represents an alternative within a<c:choose> action. 

<c:when test="testCondition"> 

body content 

</c:when> 



<c:otherwise> Represents the last alternative within a<c:choose> action. 

<c:otherwise> 
conditional block 
</c:otherwise> 



<c:forEach> Repeats the nested body content over a collection of objects, or 
repeats it a fixed number of times. 

Syntax 1: Iterate over a collection of objects. 

<c:forEach [var=" varName"] 
items="co? lection" 
[\tarStatus="varStatusName"] 
[beqir\=" begin"] 
[end="end"] 
[step="step"]> 
body content 
</c:forEach> 
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Syntax 2: Iterate a fixed number of times. 
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ach [var="varName"] 

Lus="varStatusName"] 

"egin" 



er\d="end" 
[step="step"]> 
body content 
</c:forEach> 

<c:forTokens> Iterates over tokens, separated by the supplied delimiters. 

<c:forTokens i tems=" stri ngOf Tokens" 

del ims=" del i miters" 

[var=" varName"] 

[varStatus="varStatusName"] 

[beqin=" begin"] 

[er\d="end"] 

[step="step"]> 

body content 

</c:forEach> 



<c:import> Imports the content of a URL-based resource. 
Syntax 1: Resource content inlined or exported as a String object. 



<c:import url ="ur / " 
[context=" context" ] 
[var=" varName"] 

[scope=" {page | request | sessi on | appl i cati on ) "] 

[charEncoding="c/)ar£ncoc/7«g"]> 

optional body content for <c:param> subtags 

</c:import> 



Syntax 2: Resource content exported as a Reader object. 

<c:import url="ur?" 
[context="context"] 
varReader="i/(jr/?e3c/erAlame" 
[charEncodi r\g="charEncoding"]> 

body content where varReader is consumed by another action 
</c:import> 

<c:url> Builds a URL with the proper rewriting rules applied. 

Syntax 1: Without body content. 

<c:url val ue="val ue" 

[context="context"] 

[\iar="varName"] 

[scope=" (page | request | session | appl ication) "]/> 
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Syntax 2: With body content to specify query string parameters. 



iOQk; 



•ri^al ue="val ue" 
tmL=" context"] 
arName"] 

[scope=" {page | request | sessi on | appl i cati on) "]> 

<c:param> subtags 

</c:url> 



<c:redirect> Sends an HTTP redirect to the client. 
Syntax 1: Without body content. 

<c:redirect ur]="value" [context="context"]/> 

Syntax 2: With body content to specify query string parameters. 

<c:redirect ur]="value" [context="context"]/> 

<c:param> subtags 

</c:redirect> 

<c:param> Adds request parameters to a URL. Nested action of<c:import>, 
<c:url>, <c:redirect>. 

Syntax 1: Parameter value specified in attribute val ue. 

<c:param r\ame="name" value="i/a/ue"/> 
Syntax 2: Parameter value specified in the body content. 

<c:param name="r;affle"> 
parameter value 
</c:param> 



JSTL Formatting Library Syntax 

The Formatting library provides tags to implement I18N support for both lan- 
guage and customs. 

<fmt:setLocale> Stores the specified locale in the 

javax.servlet.jsp.jstl . f mt .locale configuration variable. 

<fmt:setLocale val ue=" loca le" 
[ va ri ant=" t/ar /ant " ] 

[scope=" (page | request | sessi on | appl i cati on) "]/> 
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<fmt:bundle> Creates an il8n localization context to be used by its body 
content. 



DropBoaks 

body con: 



(die basename="basename" [prefix="preffx"]> 
content 
</fmt:bundle> 



<fint:setBundle> Creates an il8n localization context and stores it in the scoped 
variable or the j avax . servl et . j sp . j stl . fmt . 1 oca 1 i zati onContext con- 
figuration variable. 



<fmt : setBundl e basename="i)asef?ame" 
[var=" varName"] 

[scope=" { page | request session appl i cati on) "]/> 


<fmt:message> Looks up a localized message in a resource bundl 
Syntax 1: Without body content. 


e. 


<fmt:message key="messageKey" 
[bundl e="resourceBundle"] 
[var=" varName"] 

[scope=" {page request sessi on appl i cati on ) "]/> 






Syntax 2: With a body to specify 


message parameters. 




<fmt:message key= "messageKey" 
[bundl e=" resourceBundl e"] 
[var=" varName"] 

[scope=" {page request sessi on appl i cati on ) "]> 

<fmt:param> subtags 

</fmt:message> 







Syntax 3: With a body to specify key and optional message parameters. 



<fmt: mess age [bundl e=" resourceBundl e"] 
[var=" varName"] 

[scope=" {page | request | sessi on | appl i cati on ) "]> 
key 

optional <fmt:param> subtags 
</fmt:message> 

<fmt:param> Supplies a single parameter for parametric replacement to a 
containing <fmt :message> action. 

Syntax 1: Value specified via attribute value. 

<fmt:param val ue="messageParameter" /> 
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Syntax 2: Value specified via body content. 



am> 
tent 
3ram> 



<fmt:requestEncoding> Sets the request's character encoding. 

<fmt : request Encodi ng [val ue=" charsetName"]/> 

<fmt:timeZone> Specifies the time zone in which time information is to be 
formatted or parsed in its body content. 

<fmt : timeZone val ue="timeZone"> 

body content 

</fmt:timeZone> 



<fmt:setTimeZone> Stores the specified time 
time zone configuration variable. 


zone in a scoped variable or the 


<fmt rsetTimeZone val ue="t imeZone" 
[var=" varName"] 

[scope=" {page request sessi on appl i cat i on ) "]/> 






<fmt:formatNumber> Formats a numeric value in a locale-sensitive or cus- 
tomized manner as a number, currency, or percentage. 

Syntax 1: Without a body. 


<fmt: format Number val ue="numeri cVal ue" 





[type=" (number | currency | percent)"] 
[ pa ttern="customPat tern"] 
[currencyCode="currencyCoc/e"] 
[currencySymbol =" currencySymbol "] 
[groupingUsed=" I true | fal se) "] 
[max I ntegerDi gits="/»axl/7tegerD/g7ts"] 
[mini ntegerDi gi ts=" mini ntegerDi gi ts " ] 
[maxFracti onDi gi ts="maxFractionDigi ts"] 
[mi nFracti onDi gi ts="minFractionDigi ts"] 
[var="varName"] 

[scope=" {page | request | sessi on | appl i cati on) "]/> 
Syntax 2: With a body to specify the numeric value to be formatted. 

<fmt: format Number [type=" {number currency | percent ) "] 

[ pa ttern="customPat tern"] 

[currencyCode="currencyCode"] 

[currencySymbol =" currencySymbol "] 

[groupingUsed=" {true | false) "] 

[max I ntegerDi gits="/n3xl/?te<?erD/g7ts"] 

[mi n I ntegerDi gi ts=" 'mini ntegerDi gi ts"] 

[maxFracti onDi gits="maxFract;oA)D;g; ts"] 
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[mi nFracti onDi gi ts=" mi nFrdcti onDi gi ts"] 




1 1 sessi on | appl i cati on} "]> 
formatted 



<fmt:parseNumber> Parses the string representation of numbers, currencies, 
and percentages that were formatted in a locale-sensitive or customized 
manner. 



Syntax 1: Without a body. 



<fmt:parseNumber val ue="numericValue" 
[type=" (number currency | percent) "] 
[pa tterr\=" customPat tern"] 
[parse Local e=" parseLoca le"] 
[i ntegerOnly=" ( true | fal se ) "] 
[var="i/<3rAl<3me"] 

[scope=" {page | request | sessi on | appl i cati on) "]/> 



Syntax 2: With a body to specify the numeric value to be parsed. 









<fmt:parseNumber [type=" {number currency percent) "] 

[ pa ttern=" customPat tern"] 

[pa rse Loca 1 e=" parseLocal e"] 

[integerOnly=" (true false)"] 

[\iar="varName"] 

[scope=" (page request sessi on appl i cati on ) "]> 
numeric value to be parsed 
</fmt:parseNumber> 













<fmt:formatDate> Allows the formatting of dates and times in a locale-sensi- 
tive or customized manner. 



<fmt:formatDate val ue="date" 

[type=" ( time | date | both)"] 

[dateStyl e=" (defaul t short | medium | 1 ong | ful 1 ) "] 

[timeStyl e=" ( defaul 1 1 short medi urn j long j full }"] 

[pattern="custo/»Patiern"] 

[timeZone=" timeZone"] 

[\iar="varName"] 

[scope=" (page | request | sessi on | appl i cati on) "]/> 



<fmt:parseDate> Parses the string representation of dates and times that 
were formatted in a locale-sensitive or customized manner. 



Syntax 1: Without a body. 

<fmt : parseDate val ue= "da teString" 

[type=" ( time | date | both) "] 

[dateStyl e=" (defaul 1 1 short medi um 1 ong | ful 1 ) "] 
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[var= 



[timeStyl e=" (def aul 1 1 short medi um 1 ong | ful 1 ) "] 
[£>attern=" customPattern"] 
*flie="tj'meZone"] 
^cal e=" parseLoca le" ] 
"varName"] 

[scope="(page| request | sessi on application) "]/> 



Syntax 2: With a body to specify the date value to be parsed. 

<fmt:parseDate [type=" { ti me | date | both) "] 

[dateS ty 1 e=" (default] short medi urn 1 ong | ful 1 ) "] 

[timeStyl e=" (def aul 1 1 short medi utn 1 ong | ful 1 ) "] 

[ pa ttern=" customPattern"] 

[tmelor\e=" ti meZone" ] 

[pa rseLoca 1 e=" parseLocal e"] 

[var=" varName"] 

[scope=" (page | request | sessi on | appl i cati on) "]> 

date value to be parsed 

</fmt:parseDate> 



JSTL SQL Library Syntax 

The SQL library allows the JSP author to directly access an SQL database 
through the tags it provides. 

<sql:query> Queries a database. 

Syntax 1: Without body content. 

<sql : query sql ="sqlOuery" 

var=" varName" [scope=" (page | request | sessi on | appl i cat ion) "] 
[dataSource="c/ataSource"] 
[maxRows=" maxRows" ] 
[startRow=" startRow"]/> 

Syntax 2: With a body to specify query arguments. 

<sql:query sql ="sqlOuery" 

var=" varName" [scope=" (page | request | sessi on | appl i cati on ) "] 

[dataSource="c/ataSource"] 

[maxRows=" maxRows" ] 

[startRow="start/?ow"]> 

<sql :param> actions 

</sql :query> 

Syntax 3: With a body to specify query and optional query parameters. 

<sql : query var=" varName" 

[scope=" (page | request | sessi on | appl i cati on ) "] 

[dataSource="c/ataSource"] 
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[maxRows="max/?ows"] 




<sql:update> Executes an SQL INSERT, UPDATE, or DELETE statement. In addi- 
tion, SQL statements that return nothing, such as SQL DDL statements, can be 
executed. 



Syntax 1: Without body content. 


<sql : update sq]=" sql Update" 
[dataSource=" dataSource"] 

[var="i/arAfame"] [scope=" (page request sessi on appl icati on ) "]/) 




Syntax 2: With a body to specify update parameters. 




<sql : update sql = " sqllJpdate" 
[dataSource=" dataSource"] 

[var=" varName"] [scope=" (page request sessi on appl i cati on ) "]> 
<sql :param> actions 
</sql : update) 




Syntax 3: With a body to specify update statement and optional update 
parameters. 


<sql :update [dataSource="d<3t<35ource" ] 

[var="i/arAlame"] [scope=" (page request session appl i cati on) "]> 

update statement 

optional <sql :param> actions 

</sql : update) 





<sql:transaction> Establishes a transaction context for < sql : query > and 
<sql :update> subtags. 



<sql :transaction [dataSource="dataSource"] 

[i sol ati or\=isol at ionLevel]> 

<sql :query> and <sql :update> statements 

</sql :transaction> 

i sol ati onLevel ::= "read_committed" 

"read_uncommitted" 

"repeatable_read" 

"seri al i zabl e" 

<sql:setDataSource> Exports a data source either as a scoped variable or as 
the data source configuration variable (javax.servlet.jsp.jstl .sql . 
dataSource). 

<sql :setDataSource 

(dataSource="c/ataSource" 

ur]="jdbcUrl" 
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[dri ver="c/r? verCl assName"] 
[iiser=" userName"] 
[|ysjp*d=" password"] ) 
[|\=y^r«ame"] 

[scope=" (page | request | session | appl ication} "]/> 

<sql:param> Sets the values of parameter markers (" ? ") in an SQL state- 
ment. Subtag of SQLExecuti onTag actions such as <sql : query > and 
< s q 1 : update). 

Syntax 1: Parameter value specified in attribute val ue. 

<sql : param val ue="i/a/tve"/> 
Syntax 2: Parameter value specified in the body content. 



<sql :param> 
parameter value 
</sql :param> 






<sql:dateParam> Sets the values of parameter markers (" ? ") in an SQL state- 
ment for values of type java.util .Date. Subtag of SQLExecuti onTag 
actions, such as < sq 1 : query> and <sql : update). 


<sql :dateParam val ue= 


"value" type="[timestamp|" 


time date]"/) 













JSTL XML Library Syntax 

The XML library consists of a set of tags designed to make the processing of 
XML documents easier for the page author. 

<x:parse> Parses an XML document. 

Syntax 1: XML document specified via a String or Reader object. 

<x:parse m\ = "XMLDocument" 

|var="i/ar" [scope="scope"] | varDom="var" [scopeDom="scope"] ) 

[systemld=" systemld"] 

[filter="f7'Jter"]/> 

Syntax 2: XML document specified via the body content. 

<x:parse 

|var="i/ar" [scope="scope"l | varDom="var" [scopeDom="scope"] ) 
[systemld=" systemld"] 
[filter="f;'7ter"]> 
XML Document to parse 

</x:parse> 
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<x:out> Evaluates an XPath expression and outputs the result of the evalua- 
tion to the current JspWriter object. 

elect-" XPathExpressi on" [escapeXml=" {true | false) "]/> 

<x:set> Evaluates an XPath expression and stores the result into a scoped 
variable. 

<x:set sel ect=" XPathExpressi on" 
var="varName" 

[scope=" {page | request | sessi on | appl i cati on ) "]/> 



<x:if> Evaluates the XPath expression specified in the sel ect attribute and 
renders its body content if the expression evaluates to true. 



Syntax 1: Without body content. 






<x: i f sel ect=" 'XPathExpressi on" 
\tar="varName" 

[scope=" (page request sessi on appl i cati on) "]/> 






Syntax 2: With body content. 






<x: i f sel ect=" XPathExpressi on" 
[var=" varName"] 

[scope=" (page request sessi on appl i cati on) "]> 

body content 

</x:if> 






<x:choose> Provides the context 


f 


or mutually exclusive conditional execution. 


<x:choose> 

body content (<x:when> and <x: otherwise) subtags) 

</x:choose> 





<x:when> Represents an alternative within the <x:choose> action. 



<x:when sel ect="XPathExpressi on"> 

body content 

</x:when> 

<x:otherwise> Represents the last alternative within the <x : choose) action. 

<x:otherwise> 
conditional block 
</x:otherwise> 
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<x:forEai 



<x:forEach> Evaluates the given XPath expression and repeats its nested 
body content over the result, setting the context node to each element in 
ion. 



ch[var="i/ar/Vame"] se]ect="XPathExpression"> 
body content 
</x:forEach> 



<x:transform> Applies an XSLT stylesheet transformation to an XML 
document. 



Syntax 1: Without body content. 



<x:transform 

m\ = " XMLDocument" xsl t="XSLTStyl esheet" 

[xml SystemId="A'MZ.Syste/n/d" ] [xsl tSy stemld= "XSLTSys temld"~\ 

[ ( var=" varName" [scope=" scopeName"] | resul t=" resultObject" ) ]/> 

Syntax 2: With a body to specify transformation parameters. 



<x: transform 

m] = "XMLDocument " xsl t=" XS LTSty 1 esheet" 

[xml Systemld=" XMLSystemld"] [xsl t System ld="XSL TSystemld"] 

[ ( va r=" v a rNaine" [scope=" scopeName" ] | resul t=" resultObject" ( ] 

<x:param> actions 

</x:transform> 



Syntax 3: With a body to specify XML document and optional transformation 
parameters. 



<x: transform 

xsl t=" XS LTStyl esheet" 

xml Systemld=" XMLSystemld" xsl tSystemId="^S/_rSystem/d" 
[(var="i/<3r/Vame" [scope=" scopeName"] \ resul t=" resultObject" )] 
XML Document to parse 
optional <x:param> actions 

</x:parse> 



where scopeName is {page|request|session|appli cat ion) 



<x:param> Set transformation parameters. Nested action of<x:transform>. 
Syntax 1: Parameter value specified in attribute val ue. 



<x:param name="/?ame" value="i/a/ue"/> 



Syntax 2: Parameter value specified in the body content. 



<x:param name="naffle"> 
parameter value 
</x:param> 
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m akarta Struts uses lots of terms that may not be familiar to you. In this 
J- glossary, we collect the terms that we have defined throughout the book 
and then add some more. 

abstract class: A class, such as the Acti on class, that has at least one 
abstract method and must be subclassed before you can use it. 

application context: A name that refers to a particular Web application, 
including the data logic and resources. 

assertion: A statement that evaluates an expression and throws an exception 
if not true. 

attribute: A property of a tag. See elements. 

authentication: The process of making sure users are who they say they are. 

authorization: The process of granting a user permission to see a page or 
perform an operation. 

chained exception: A mechanism in which one exception is caused by a dif- 
ferent exception. You can think of it as exception piggy-backing. 

checked exception: An error that the application programmer must catch in 
atry/catch block or throw a similar exception. 

collection: An interface and the root definition of a set of classes that hold 
groups of data objects. 

commit: To save a transaction. 

component: A small, self-contained program that forms part of a larger 
application. 

custom tag library: Bundles of custom tags that people have created to 
extend the functionality of JSP through the use of HTML-like tags. They are 
accompanied by a descriptor file called a Tag Library Descriptor (tld). The 
Struts and Struts-EL tag libraries are examples of this extended functionality. 

Data Transfer Object (DTO): An object that carries data from one layer to 
another in an application. 

declarative security: A mechanism in which application security is expressed 
in a declarative syntax in the Struts configuration files. 
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definitions, Tile: A mechanism that allows you to specify all the attributes 
that go to make up a Tile in a reusable structure. 



ttern: A paradigm that structures an application. The Struts design 
called Model-View-Controller (MVC) and applies to Web applications. 



Document Type Definition (DTD): A definition of the XML grammar used in 
an XML document 

dynamic: Web pages that adapt in response to a user's request. 

elements: The part of the grammar in a DTD that defines a tag. 

entity: A shortcut to a commonly used value in a DTD. See Document Type 
Definition. 

exception: An event that occurs during the execution of a program that dis- 
rupts the normal flow of instructions. 

expression language: A scripting language used in JSTL and JSP 2.0 to create 
expressions for evaluation. 

extension point: A dummy method made to be overridden in a subclass. 
See hook. 

formbean: An extension of the Acti on Form abstract class that provides a 
consistent container to store the View's form data for presentation to the 
Controller. 

forward: More exactly known as Acti on Forward, a mechanism that defines 
the passing of control from one module to another. 

framework: An application that provides foundational functionality that must 
be extended for specific needs. 

getter: A method that begins with get and returns a property's value. 

handler: Code that interprets what action to take based on a request. 

helper classes: Generic classes that are created by the programmer to provide 
additional logic or data structure or both for the application. Their purpose 
is to improve the flexibility and structure of the programming code. 

hook: A no-function method designed to be overridden when the class is 
extended. See extension point. 

I18n: A shortcut for internationalization. 

implementation: The actual program that functions according to a 
specification. 

implicit objects: Objects already defined by the system and made available to 
the programmer. 

JavaBean: A special form of Java class that follows certain rules, including 
the methods it uses and its naming conventions. 
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JavaBeans component architecture: Defines how Beans are constructed and 
how they interact with the program in which they are used. 



let container: See Web container. 

layout: See template. 

literal: A constant that is taken at face value and not interpreted, such as the 
String literal "abed". 

logging: Writing messages about events in an application so that you can look 
at them later and see what your application actually executed. You might write 
these message to the system console, a file on disk, or an e-mail message. 

map: An interface and root definition of a group of classes that hold data ele- 
ments against keys. Provide the key, and it will return the piece of data. 

module: A set of components in a Web application that are accessed under a 
different name. 

persistence: A situation in which the lifetime of the data exceeds the lifetime 
of the application. The data continues to exist after the application or even 
the computer has been shut down. The next time the application starts, the 
same data is still available. 

perspective: In Eclipse, a feature that allows you to change the overall 
arrangement of the work area to suit your current task. 

pipeline: A processing mechanism that moves data and control along a par- 
ticular path. 

plug-in: A class that is added to the main application to provide additional 
functionality. 

public: A property of Java object methods that tell Java they are available to 
anyone using the Bean or class. 

realm: Identifies a set of users, their passwords and their associated roles. 

refactoring: Rewriting portions of code to make the resulting code simpler, 
more readable, and more efficient. 

regular expression: A concise way to describe and search for complex string 
patterns. 

resource bundle: A file that contains all the text that the Struts application 
will display to the user. 

roles: A way of grouping users. A role represents a set of permissions that 
you want to apply to a certain group of users. 

rollback: To reverse a transaction. 

runtime expression: A Java-based syntax for writing expressions. Used in 
older tag libraries and JSP version 1.2 and below. 
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scoped variable: A variable that exists in one of the four scopes — page, 
request, session, or application. 



Short Java code fragments embedded in a JSP page that are exe- 
the server side to create the dynamic part of the presentation, so 
that the page can modify its output to reflect the user's request. 



separation of concerns: A programming technique to keep from intermingling 
different functional areas, such as separating the visual layout of a Web page 
from data. 

servlet: A part of a Web application that can take requests from a Web browser 
and, after some processing, return an assembled Web page. This object is 
defined by the Java Servlet Specification. 

servlet container: A Web application server that adheres to the Java Servlet 
Specification and can run Java Servlets. 

setter: A method that begins with set and sets the value of a property. 

skin: A color combination and style that control's a page's or application's 
look — and feel. Also what covers your entire body. 

specification: A document that describes all the details of a technology. 

tag: In an XML, JSP or HTML document, a definition of an element to appear 
in the document. 

template: A definition of how a page should look but not what content should 
go into it. The template includes the page markup that describes the structure 
of the page and names the additional segments that the page should include 
as content. Sometimes called a layout. 

template engine: The developer defines templates that describe the look and 
feel of a page, and the engine merges the page data together with the template 
to create the presented page. This methodology offers flexibility in site design, 
easy design development for graphics people, and control of the consistency 
of site appearance. 

thread: A path of execution of the program's code. A Java Web application has 
multiple paths running simultaneously so that more than one user can use an 
application at the same time. 

thread-safe: Code that doesn't allow conflicts when multiple clients run the 
code simultaneously. 

tiles: In a template, additional segments that the page should include as 
content. 

Web container: A program that manages the components of a Web application, 
in particular JSP pages and Java Servlets. Sometimes called a JSP/Servlet 
container. 
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* (asterisk) 

DTD element suffix, 161 
SQL wildcard, 122-123 
[ ] (brackets) EL operator, 229 

# (number sign) comment prefix, 67 
. (period) EL operator, 229 

+ (plus sign) DTD element suffix, 161 
? (question mark) 

DTD element suffix, 161 

SQL parameter marker, 243, 372 
" " (quotation marks) XML parameter 

delimiters, 165 
; (semicolon) 

path prefix, 120 

SQL command suffix, 121 
/ (slash) module prefix, 178, 182 



Accelebrate training course, 341 

Acti on class 
authentication using, 75-78, 101, 266-267 
Controller role of Acti on subclass, 20, 92, 
100-108 

exception handling using, 201-202 
execute method, 100, 101-103, 105 
extending, 100-108 

RequestProcessor class, interaction 

with, 100 
subclasses, predefined, 103-108 
action mapping 
Acti onForm class, using in, 100 
described, 82, 176 

formbean, associating with, 151, 178 
forward processing, 99, 177 
include processing, 99, 177 
path, determining from request URL, 98 
path, module-relative, 177-178 
RequestProcessor role in, 98, 99 
security role, associating with, 178 
servlet, mapping to URL pattern, 166 



Struts -confi g . xml file configuration, 
176-179,296-297 

val idate method, invoking, 178 
Action Scripting plug-in, 332-333 
action tag, 14, 176-177, 273 
acti on variable, 307 
Acti onConf i g class, 93 
ActionError class, 70-71, 153-155, 198 
Acti onErrors class, 77, 153-155 
Acti onForm class. See also form 

action mapping, using in, 100 

button, referencing in Acti on Form 
subclass, 69 

DynaActi onForm class compared, 157 

extending, 70 

formbean, Acti onForm subclass relation 

to, 69, 172 
request handling role, 20, 99 
RequestProcessor class, interaction 

with, 99, 151 
struts -confi g. xml file configuration, 

299-300 

val idate method, 70, 71, 99, 153, 178 

View, association with, 69 
Acti onFormBean class, 93 
ActionForward class 

Controller role, 93 

exception handling using, 203 

Logi nActi on class, retrieval of 
Acti onForward object by, 77 

RequestProcessor class, interaction 
with, 100, 101 

sort method, 105 

struts -confi g . xml file configuration, 77, 
176-177 
Acti onMappi ng class 

Controller role, 93, 100 

forward attribute, 99 

include attribute, 99 

RequestProcessor class, interaction 
with, 99 

security, 178 
acti on-mappi ngs tag, 177-179 
Acti onMessage class, 155 
Acti onMessages class, 155 
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Acti onServl et class 
Controller role, 20, 92, 93-98 
^^uaj£VfiL sfetting^using, 96 

ln7tiaTizmg7y4-97,'T54-l 65 
message resource setup using, 96-97 
module, instantiating using, 96-97 
plug-in initialization role, 210, 211-212 

process method, 97 

request handling by, 92, 93, 97 

struts-conf i g . xml file 
configuration, 179 

URL mapping, 63, 166 

web . xml file configuration, 80, 94, 163-166 
Add Language dialog box 

Internet Explorer, 146 

Netscape Navigator, 147 
add method 

Acti onError class, 154-155 

LookupDi spatchActi on class, 107 
Al bumActi on class, 306, 312-318, 321-322 
Al bumBean class, 315, 318-322 
Al bumDTO class, 308, 315, 317, 319 
a 1 bumFo rm class, 310-312, 314, 315 
Al bumVa 1 i dati on class, 312 
Ant IDE, 33 

Apache Cocoon project, 21, 138 
Apache Software Foundation. See ASF 
Apache Tomcat 

downloading, 29 

Eclipse, configuring for, 37 

Eclipse, starting from, 38, 43 

home page, default, 33, 43 

installing, 29-31 

Linux environment, 31 

Mac OS X environment, 31 

MySQL class library, adding, 115-117 

password, 31 

port setup, 31, 32 

SDK considerations, 37 

starting, 32, 38, 43 

testing, 32, 38 

Web container, as, 12 
Apache Wiki Web site, 340 
Appl i cati onResources file, 59, 67-68, 

144-145, 221 
archive.apache.org Web site, 247 
ArrayList Java class library, 128 
ASF (Apache Software Foundation), 10 
assertion, 199-201 



asterisk (*) 

DTD element suffix, 161 

SQL wildcard, 122-123 
authentication. See also password; security 

Acti on class, using, 75-78, 101, 266-267 

BASIC style, 275, 276-278 

CLIENT-CERT style, 275 

described, 265-266 

DIGEST style, 275 

FORM style, 275 

forwarding user upon failure, 265 
JAAS, 271 

JavaBean, using to store authentication 

data, 74-75, 76 
RequestProcessor class, using, 267-270 
validation against database, 124-126 
validation against HashMap construct, 75 
validation, formbean role in, 82 
validation, Logi nBean role in, 76-77 
validation using Validator plug-in, 214, 

219-221 

web . xml file, authentication method 
definition in, 275, 277 
authorization 
database, against, 295 
described, 265, 266 
forwarding user upon failure, 265 
JAAS, 271 

Logi nBean, using, 294 
permission, checking, 267 
security role, using, 273, 276 
struts-conf i g . xml file 

configuration, 273 
web . xml file configuration, 273-274 
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b a d e r r o r . j s p file, 207-208, 324 

BasicDataSource class, 132 

bean : tags, 143, 232, 347-348 

Borland JBuilder IDE, 34, 335 

brackets, ([ ]) EL operator, 229 

breakpoint, debugging using, 87-88 

BSF (Bean Scripting Framework), 332 

B2B (Business-to-Business) application, 110 

build path, 56, 58 

build, xml file, 334 

business 

logic, 10 

object, 110-112 
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button, creating 
Acti onForm subclass, referencing button 

DropB0§k ; £ 

image button, 329-330 

input field button, 348-349 

logoff button, 306, 322 

message resource, generating label using, L 

radio button, 357 

reset button, 357-358 

submit button, 106, 294, 359 
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c : tags, 234-238, 253, 363-366 

Capability Maturity Model (CMM), 191 

Castor ORM, 128 

catch block, 196, 235, 364 

Cavaness, Chuck ("Jakarta Struts: Seven 

Lessons from the Trenches"), 339 
check box, creating, 349-350, 355 
class. See specific class 
classpath, 56 

CMM (Capability Maturity Model), 191 

Cocoon project, 21, 138 

code guard method, 283-284 

Collection, 152 

commenting code, 14, 67 

commit (transaction save), 243 

commons libraries, 41-42, 98, 282 

compiling, 56, 58, 72, 200 

component, 14 

concern, separation of, 242 

concurrency, 12 

conditional expression, 235, 364 
connection pooling, 132-133 
Connector/J driver, 113, 114-115 
Consol eAppender class, 285 
constant element, 222-224 
consultant, hiring, 340 
context, 80, 141, 143, 162-163, 165 
context-param tag, 143, 162-163 
Controller. See MVC (Model-View-Controller) 
control 1 er tag, 179-181 
convertID method, 314-315 
Core tag library, 234-238, 363-366 
Create JRE dialog box (Eclipse), 39 
createUser method, 303-304 
c.tldfile, 56 
cur variable, 241 



CustomExceptionHandler class, 

205-207, 323 
Customize Perspective dialog box (Eclipse), 36 

CustomRequestProcessor class, 268-269 
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Dai lyRol 1 i ngLogAppender class, 286 
Data Definition Language (DDL), 118 
Data Manipulation Language (DML), 118 
Data Transfer Object. See DTO 
datatype, converting, 149-150 
database. See also MySQL database 
management system 

ArrayList, holding row data in, 128 

authentication against, 124-126 

authorization against, 295 

connection, establishing, 125 

connection, pooling, 114, 130-135, 169 

creating, 120-121 

data source, 132-135, 169-171, 243, 290, 371 
deleting data, 107, 315-316, 320, 371 
driver, 113 
indexing, 152 

inserting data, 107, 121-122, 243, 313, 320 

JDBC, 113, 124-126 

listing all databases, 121 

LoginBean class, accessing from, 124-129, 

132-133 
Model, connecting to, 123-130 
OODBMS, 128 
ORM, 128, 330 

query, 122-123, 125-129, 242, 318-319, 

370-371 
RDBMS, 113 
schema, 289 

SQL script, interacting with using, 122 

table, creating, 121 

transaction, 129, 243, 371 

updating, 243, 316-317, 321, 371 

View, passing query result to, 126 
DataSource class, 133, 169, 290 
data-source tag, 170 
DataSourceConf i g class, 93 
data-sources tag, 169-170, 171 
DBCP (Database Connection Pooling), 114, 

131-132, 170-171 
DBExcepti on class, 205 
DDL (Data Definition Language), 118 
debugging, 87-88, 96, 180 
decl a rati on tag, 14 
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definition (Tiles framework mechanism), 
260-261 

f^t^ffilui f^t^J, 316, 320 

d e s c r Tp t ron ' ag, T&4, 1 72 

design pattern, 10, 15, 18-23. See also MVC 
(Model-View-Controller) 

Design Patterns: Elements of Reusable Object- 
Oriented Software (Gamma, Helm, 
Johnson, and Vlissides), 18 

destroy method, 97-98, 210, 212 

Dev Shed Web site, 118 

developer.com Web site, 196 

directive tag, 14 

Di spatchActi on class, 104-106 

Display tag library, 246 

di s p 1 ay-name tag, 164, 172 

DML (Data Manipulation Language), 118 

.do files, 63, 92 

Document Type Definition. See DTD 
documentation, 43-44, 333-334, 343 
dom . j ar file, 231 
downloading 

Apache Tomcat, 29 

Connector/J, 114-115 

Eclipse, 34 

Jakarta Struts, 40 

Java, 26 

Login example application, 59 

MySQL, 114 
Dreamweaver software, 14 
DTD (Document Type Definition). See also 
XML (extensible Markup Language) 

attribute, 161, 162 

element, 160-161 

entity, 161 

formbeanDTD, 171-172 

struts-config.xml file DTD, 169 

syntax, 160-161 

Validator plug-in DTD, 213, 215 

web.xml file DTD, 160 
DTO (Data Transfer Object), 17, 129 
DynaActionForm class, 156-157, 173, 224, 291 
DynaVal idatorForm class, 173, 214, 291 

Easy Struts plug-in, 335-336 

Eclipse IDE 
Apache Tomcat, configuring for, 37 
Apache Tomcat, starting from, 38 



compiling, 72, 200 
Create JRE dialog box, 39 
Customize Perspective dialog box, 36 
Debug Perspective, 87-88 
downloading, 34 
Editor Selection dialog box, 60 
file association, 60 
filtering, 54-55 

Folder Selection dialog box, 72 

importing file, 54-58, 64 

installing, 34-35 

introduced, 14 

JAR Selection dialog box, 58 

Java Element Filters dialog box, 54-55, 71 

JAVA perspective, 50 

JRE, 37-39 

library file, working with, 54, 56-58 
MySQL, configuring for, 115-116 
New File dialog box, 64 
New File Type dialog box, 60 
New Folder dialog box, 52 
New Java Class dialog box, 73 
New Project dialog box, 51 
New Source Folder dialog box, 52 
output folder, specifying default, 72 
package, creating, 71 
Package Explorer, 52-53 
Perspectives feature, 50-51 
plug-ins, 33-34, 35-39, 335-336, 342 
Preferences dialog box, 36, 37, 60 
project, creating, 51 
Properties for Login dialog box, 57 
starting, 43 

struts -confi g . xml file, adding, 83 
view, 51 
Web site, 14 

web . xml file, adding, 80-81 
Edit File System Variable dialog box 

(MySQL), 120 
Edit System Variable dialog box (Windows), 28 
Editor Selection dialog box (Eclipse), 60 
EJB (Enterprise JavaBean), 164 
EL (Expression Language), 227-229 
element, DTD, 160-161 
empty operator, 229 
Enterprise JavaBeans For Dummies 

(Rinehart), 111 
entity, 161 
Error class, 192 
errorBundl e variable, 239 
error, jsp file, 324 
Exadel Web site, 342 
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Excepti on class, 192, 197 
exception handling 
|~"\ ^ _ ^ ^mDdflsslusimj, 201-202 

U i O D E3€/\3'i^S ss using 203 

assemon, using, 139-201 
catch block, using, 196, 235, 364 
chaining, 198-199 

checked/unchecked exception, 193, 207 

class, creating custom for, 197-198, 205-207 

CMM level, 191 

DBExcepti on, 205 

declarative, 203-205, 207, 324 

execute method, customizing for, 205-206 

failure, controlling, 202 

f i n a 1 1 y block, using, 1 94 

global exception, 174-175, 203, 204-205, 207 

information about exception, retrieving, 196 

information about exception, saving, 202 

IOException error, 192, 193-194 

local exception, 204-205 

logging exception, 197 

message to user, displaying, 202, 207-208 

method exception, 193-194 

module exception, 198, 206, 295, 323, 324 

recovery, 192, 202 

RequestProcessor class, using, 203 
runtime exception, 192, 193, 198, 

207-208, 324 
SQLException error, 195, 198, 202, 308 
stack trace information, retrieving, 196-197 
try /catch block, using, 192-193 

excepti on tag, 203, 204, 206 

Excepti onConf i g class, 93 

Excepti onHandler class, 1 98, 203, 204, 
205-207, 295 

execute method 
Action class, 100, 101-103, 105 
Al bumActi on class, 313 
exception handling, customizing for, 

205-206 
JoinAction class, 301-302 
Logi nActi on class, 294-295 
Logoff Acti on class, 322 
LookupDi spatchActi on class, 107-108 

executeQuery method, 125-126 

expression 
conditional, 235, 364 
identifier item, 228 
key, 228 
literal item, 228 
operator, 229 
regular, 218 



runtime, 227 

tag element, 14 

value, 228 
Expression Language. See EL 
Expresso plug-in, 128, 331-332 
extensible Markup Language. See XML 
extensible Stylesheet Language. See XSL 
extensible Stylesheet Language 

Transformation. See XSLT 
extension point, 268 

field tag, 220 

file upload, configuring, 180, 181 

filtering, 54-55 

finally block, 194 

f i ndAl bum method, 315, 318-319 

f mt : tags, 142, 143, 238-241, 366-370 

fmt.tldfile, 56, 62 

folder access, restricting, 277-278 

Folder Selection dialog box (Eclipse), 72 

footer, 250, 251, 253, 258, 292 

footer, jsp file, 251, 253, 292 

form 

authentication, FORM style, 275 
dynamic, 156-157, 173, 224, 291, 299-301 
focus, 63 

HTML form, 232-233 
resetting, 70, 152, 357-358 
submitting, 63, 149, 294, 359 
validating, Acti onError object created 

upon failure, 153-154 
validating, declarative, 293, 300 
validating dynamic form, 157, 291, 299-301 
validating using val idate method, 70-71, 

151,317 

validating using Validator plug-in, 213-222, 

290, 291, 293-294, 299-301 
validating via overriding val idate 

method, 152-154 
form tag, 220 

Formatting tag library, 238-241, 366-370 
formbean 

action mapping, associating with, 151, 178 
ActionForm subclass formbean, 69, 172 
defining, 69-74, 171-174 
described, 69, 149 
DTD, 171-172 

DynaActionForm subclass formbean, 156, 
157, 173 
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formbean (continued) 
icon, assigning to, 172 

^^^^^ ^I^I^Vvjr 1 ' 

parameter, passingto, 172 
scope, 151, 152 

struts -confi g . xml file configuration, 
150-151, 171-174 

val idate method of, 70-71, 82, 151, 153 
View/Controller interaction using, 149-151 

form-bean tag, 82, 151, 156, 172 

FormBeanConf i g class, 93 

form-beans tag, 82, 171-172 

form-error-page tag, 275 

form-login-config tag, 275 

f orm-1 ogi n-page tag, 275 

form-property tag, 173 

form-validation tag, 213 

forward mechanism, 138 

Forwa rdActi on class, 103 

Forwa rdConf i g class, 93 

FreeMarker project, 138 
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Gamma, Erich (Design Patterns: Elements of 
Reusable Object-Oriented Software), 18 

GenericDataSource class, 132 

getAl 1 Users method, 127, 128 

getConnecti on method, 133 

getDataSource method, 134 

getlnt method, 129 

getKeyMethodMap method, 107 

getMessage method, 196-197 

get Musi c method, 308-309 

getStri ng method, 129 

getter methods, 16 

gl obal -exceptions tag, 174-175, 203, 
204-205, 207 

gl obal -forwards tag, 175-176 
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handler. See exception handling; request 

handling 
HashMap construct, 75, 107 
Helm, Richard (Design Patterns: Elements of 

Reusable Object-Oriented Software), 18 
helper class, 112 
Hibernate plug-in, 330-331 



homeContent . j sp file, 292 
home . jsp file, 292 
hook, 99 

html : base tag, 348 

html : button tag, 348-349 

html : cancel tag, 349 

html : checkbox tag, 349-350 

html : errors tag, 68, 71, 155, 350 

html rfiletag, 350-351 

html : form tag, 232,351 

html : frame tag, 351 

html : hidden tag, 351-352 

html : html tag, 352 

html : image tag, 329, 352-353 

html : img tag, 353 

html : j a v a s c r i pt tag, 354 

html : 1 ink tag, 354 

html : messages tag, 155, 355 

html : mul ti box tag, 355 

html : opti on tag, 355 

html : opti ons tag, 356 

html : opti onsCol 1 ecti on tag, 356 

html : password tag, 356-357 

html : radi o tag, 357 

html : reset tag, 357-358 

html : rewri te tag, 358 

html : select tag, 358-359 

html : submi t tag, 359 

html :text tag, 359-360 

html : textarea tag, 360 

html : xhtml tag, 360 

HTTP (Hypertext Transfer Protocol), Web 

container support, 12 
HTTPS (Hypertext Transfer Protocol, 

Secure), 332 
HttpServl etResponse class, 176 



I18N (internationalization), 62-63, 67, 
139-148, 238-240, 366-367 

IBM 

BSF resources, 332, 333 
WebSphere Studio IDE, 34 
icon 

Acti onServl et, assigning to, 164 

formbean, assigning to, 172 
IDE (integrated development environment), 

33-34, 43-45. See also specific IDE 
IDEA IDE, 34 

ImageButtonBean class, 329 
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ImageButtonBeanManager extension, 
329-330 
^U^bigct Jffo 249-230 

Impornrorrffi irectory dialog box (Eclipse), 54 
include statement 
action mapping include processing, 99, 177 
directive, using, 251-252 
jsp : i ncl ude tag, using, 245, 252-253 
I ncl udeActi on class, 103-104 
indexing, 152 

i ni t method, 94, 209-210, 211 
i ni t-pa ram tag, 164, 165 
input buffer, 180 
INSTALL file, 41 
installing 

Apache Tomcat, 29-31 

Eclipse, 34-35 

Java, 26-27 

MySQL, 114 
integrated development environment. See IDE 
IntelliJ IDEA IDE, 34 
internationalization. See I18N 
Internet Explorer language preference, 

setting, 145-147 
i nval idateUser method, 126 
IoC (Inversion of Control), 330 
IOException class, 192, 193-194 
i sAdmi ni strator method, 267 
i sDepartmentHead method, 267 
IT.CappuccinoNet.com, 139 
iteration, 236-237, 361, 363-364 



JAAS (Java Authentication and Authorization 

Service), 271 
Jakarta Project, 10-11 

Jakarta Struts For Dummies Web site, 287, 325 
"Jakarta Struts: Seven Lessons from the 

Trenches" (Cavaness), 339 
j akarta -oro .jar file, 42 
JAR Selection dialog box (Eclipse), 58 
Java 

downloading, 26 

installing, 26-27 

SDK, 26, 27, 37 
Java Authentication and Authorization 

Service. See JAAS 
Java Boutique Web site, 199 
Java Database Connectivity. See JDBC 



Java Element Filters dialog box (Eclipse), 
54-55, 71 

Java Naming and Directory Interface. 
See JNDI 

Java Runtime Environment. See JRE 

Java scriptlet, 13, 14 

Java Server Faces. See JSF 

Java Servlet class group, 58 

Java 2 Enterprise Edition. See J2EE 

Java 2 Platform, Standard Edition. See J2SE 

Java Virtual Machine. See JVM 

Java XML. See JXML 

JavaBean. See also formbean 

authentication data, storing in, 74-75, 76 

class, 14, 16 

component architecture, 14 
described, 10 
design pattern, 15 
DTO, as, 17 
EJB, 164 

Model data repository, using as, 49, 74, 112 

naming convention, 15-16 

property, 15-16 

variable, referencing in, 229 

View data, representing using, 48, 69 
JAVA_H0ME environment variable, 28 
JavaServer Pages. See JSP 
java.sun.com Web site 

exceptions tutorial, 196 

Java Servlet specification, 13 

JavaBean resources, 16 

JDBC tutorial, 130 

JSF resources, 247 

JSP specification, 13 

J2EE tutorial, 274 

J2SE resources, 201 

JXML reference, 40 
JavaWorld Web site, 247 
jaxen-ful 1 .jar file, 231 
jaxp-api .jar file, 231 
JBuilder IDE, 34, 335 
JCP Web site, 247 

JDBC (Java Database Connectivity), 113, 

124-126, 130 
jdbc2_0-stext . jar file, 231 
Jdkl4Logger class, 282 
JNDI (Java Naming and Directory 

Interface), 271 
Johnson, Ralph (Design Patterns: Elements of 

Reusable Object-Oriented Software), 18 
Joi nActi on class, 300, 301-302, 304 
JoinBean class, 301, 302-304 
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joi nForm class, 299-301 
j o i n . j s p file, 294 

jp^j^Rmtlne l^ironment), 27, 37-39 

JaFxemral we5 shelz47 
JSP (JavaServer Pages). See also specific 
mechanism and functionality 

creating, 13-14 

described, 10 

editor, 14, 60 

specification, 12-13 

tag element overview, 14 

Tag library, 225 

View architecture, using as, 49, 137-139 
JSP container. See Web container 
jsp-fi 1 e tag, 164 
jsp : i ncl ude tag, 245, 252-253 
JSP/Servlet container. See Web container 
JSTL (JSP Standard Tag Library). See also 
specific tag 

Core library, 234-238, 363-366 

EL version, 234 

files associated with, 42, 231 

Formatting library, 238-241, 366-370 

introduced, 21 

RT version, 234 

SQL library, 241-244, 370-372 

XML library, 244, 372-374 
jstl .jar file, 42,231 

J2EE (Java 2 Enterprise Edition), 11, 12, 111, 
201, 274 

J2SE (Java 2 Platform, Standard Edition), 
26-27 

JUnit testing framework, 334 
JVM (Java Virtual Machine), 192 
JXML (Java XML), 40 
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Language Preference dialog box (Internet 

Explorer), 146 
language, working with in internationalized 

application, 140, 144-148 
layout. See template 
LDAP (Lightweight Directory Access 

Protocol) server, 271 
LICENSE file, 41 
life cycle management, 12 
1 i stener tag, 163 
literal (expression item), 228 



LivingLogic Web site, 335 

1 oad-on-startup tag, 164 
Log class, 282 

1 ogExcepti onCha i n method, 197 

Log Factory class, 282 

Log4J logging package, 284-286 

1 oggedi nBody .jsp file, 256 

loggedin.jsp file, 59, 64-67, 252, 258 

1 oggedi n T i 1 1 e . j sp file, 262 

logging, 197, 281-286 

1 ogi c : tags, 234-238, 253, 361-362 

Logi nActi on class, 75-77, 294-295, 296-297 

LoginActi on . java file, 59, 75-78, 88, 133 

Logi nBean class 
database access, 124-129, 132-133 
executeQuery method, 125-126 
getAl 1 Users method, 127, 128 
i nval idateUser method, 126 
Login example application, 59, 74-75, 

124-126, 132-133 
val idateUser method, 75, 76-77, 125, 126, 
295-296 

Logi nBean .java file, 59, 74-75, 124-126, 

132-133 
1 ogi n -conf i g tag, 275 
1 ogi nForm class, 73, 155, 293 
Logi nForm. java file, 59, 69-70, 71, 72-73 
1 ogi n .jsp file, 59, 61-64, 71, 155 
LogManager class, 284 
logoff mechanism, 306, 307, 309, 322-323 
LogoffAction class, 307, 322-323 
1 ogo. jsp file, 251,253, 292 
LookupDispatchAction class, 106-108, 330 
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Macromedia Dreamweaver software, 14 
Mail Archive Web site, 338 
mailing list overview, 338 
mai nTempl ate .jsp file, 257 
map (interface and root definition of class 
set), 152 

mapping, action. See action mapping 
McClanahan, Craig (Struts creator), 339 
message resource, 96-97, 141-145, 149, 154, 
181-183 

message-resources tag, 141, 181-182 
MessageResourcesConf i g class, 93 
Middleware Struts training video, 341 
Model-View-Controller. See MVC 
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module 

action mapping path, module-relative, 

^^"fcilSErl'l^tjB^ialization, referencing 

dunngTK)!] 
debugging level default, 180 
default, defining, 94 

exception handling, 198, 206, 295, 323, 324 
instantiating, 96-97 

plug-in initialization, referencing during, 212 

struts -confi g . xml file configuration, 94 

switching to another, 104 
Modul eConf i g class, 93, 96, 97 
Modul eExcepti on class, 198, 206, 

295, 323, 324 
money variable, 241 
MusicCollection.com Web site, 326 
M u s i c L i s t A c t i o n class , 306-308, 309 
Music Li stBean class, 308-309 
MVC (Model-View-Controller) 

Act i on subclass Controller role, 20, 92, 
100-108 

ActionForward class Controller role, 93 
ActionMapping class Controller role, 
93, 100 

ActionServlet class Controller role, 20, 
92, 93-98 

B2B application, Model implementation 
in, 110 

class association with View, 69-70 
data management role of Model, 109-110 
database, connecting Model to, 123-130 
database connection of Model, pooling, 
130-135 

database query result, passing to View, 126 
dependency between layers, 77 
described, 17, 18-19 
design pattern, as, 10, 18-19 
Eclipse view versus MVC View, 51 
enforcement, 19-23 

error message generation by Controller, 63 
flow control by Controller, 17, 101 
formbean, View/Controller interaction 

using, 149-151 
helper class of Model, adding, 112 
I18N of View, 139-148 
JavaBean, representing View data using, 

48, 69 

JavaBean, using as Model data repository, 

49, 74, 112 

JSP, using in View, 49, 137-139 



persistence, Model role in achieving, 113 
presentation role of View, 18 
request handling by Controller, 18 
RequestProcessor class Controller role, 

20, 92, 98-100 
struts -confi g . xml file, Controller 

configuration in, 179-181, 270 
tab libraries involved in implementing 

View, 21 

template engine, using in View, 137-138 
Views, using multiple, 49 
XML, using with View, 139 
MySQL database management system. See 
also database 
class library, 115-117 
command line, 120-121, 123 
Connector/J driver, 113, 114-115 
downloading, 114 
Eclipse, configuring for, 115-116 
Edit File System Variable dialog box, 120 
installing, 114 
starting, 118-119 
stopping, 119 
Web site, 113 



naming convention, 15-16 
NetBeans IDE, 14, 34 

Netscape Navigator language preference, 

setting, 147-148 
NewOClass (Eclipse), 73 
NewOFile (Eclipse), 64 
New File dialog box (Eclipse), 64 
New File Type dialog box (Eclipse), 60 
New Folder dialog box (Eclipse), 52 
New Java Class dialog box (Eclipse), 73 
NewOPackage (Eclipse), 71 
New Project dialog box (Eclipse), 51 
New Source Folder dialog box (Eclipse), 52 
newsgroup, 338 
now variable, 227, 240 
number sign (#) comment prefix, 67 
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object, implicit, 66, 229-230 
OJB (Object Relational Bridge), 128 
OODBMS (Object Orientated Database 
Management System), 128 
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operator, 229 
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gement system, 113 
nal mapping), 128, 330 
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paradigm, 10 

password. See also authentication; security 
Apache Tomcat, 31 
display attribute, 63 

input field, creating, 59, 63, 70, 299, 356-357 
validating, 75, 76-77, 82-83, 221, 300-301 

Path system variable, 120 

period (.) EL operator, 229 

permission, checking during authorization, 267 

persistence, 113 

pipeline, 138 

plug-in. 5ee also specific plug-in 
cost, 341-342 
described, 33 

Eclipse plug-ins, 33-34, 35-39, 335-336, 342 

initializing, 97,210,211-212 

list of available plug-ins, 329-336, 341, 342 

shutting down, 210, 212 

struts -conf i g . xml file configuration, 
183-184, 212, 215, 262-263 

Ti 1 esPl ugin class, 262-263 
PI ugln interface, 209-210 
pi ug-in tag, 183-184, 212 
PI ugi nConf i g class, 93 
plus sign (+) DTD element suffix, 161 
poLi st object, 199 
Preferences dialog box 

Eclipse, 36, 37, 60 

Netscape Navigator, 147 
pri ntStackTrace method, 197 
process method 

Acti onServl et class, 97 

RequestProcessor class, 97, 98 
processPath method, 269 
processPreprocess method, 99, 268, 269, 

297-298 
project, creating, 51, 84 
Project Refinery Web site, 343 
Properties for Login dialog box (Eclipse), 57 
property, 15-16 
public scope, 15 



question mark (?) 
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realm, 270-273, 277 
redirection, 100, 176, 233, 238, 366 
refactoring, 249, 254 
regular expression, 218 
request handling 

Acti onForm class role, 20, 99 

Acti onServl et class role, 92, 93, 97 
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serve r.xml file, 32, 270-272,277 
servlet 

action mapping, 166 

described, 9 

initializing, 164-165 

JSP translation to, 13 

naming, 164 

specification, 12, 13, 160 

startup, loading at, 164 

Web container requirement, 12 

web . xml file, configuring in, 94, 163-165 
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form validation using, 70-71, 151, 317 
formbean, of, 70-71, 82, 151, 153 
login Form class, 155 
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Web container. See also web . xml file 
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configuration file, 160 
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HTTP support, 12 

security provided by, 12, 270-278 
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web-app tag, 161-162 
web-resource-col lecti on tag, 274 
web-resource-name tag, 274 
WebSphere Studio IDE, 34 
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Eclipse, adding to, 80-81 
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Resource Bundle configuration, 142-143 
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Tiles framework configuration, 260 
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